⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

api-design

skateddu@skateddu⭐ 28 stars· last commit 14d ago· 0 open issues

REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 28 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Claude Code Python Setup

CI License: MIT Python >= 3.10 GitHub stars GitHub issues GitHub last commit

A ready-to-use .claude configuration for Python development projects with Claude Code. Includes curated agents, commands, skills, and MCP server templates.

Prerequisites

Claude Code

Claude Code requires a Pro, Max, Teams, Enterprise, or Console account (the free Claude.ai plan does not include Claude Code access).

System requirements:

  • macOS 13.0+ / Windows 10 1809+ / Ubuntu 20.04+ / Debian 10+
  • 4 GB+ RAM
  • Internet connection
  • On Windows: Git for Windows is required

Installation:

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex
# Windows (alternative: WinGet)
winget install Anthropic.ClaudeCode

After installation, navigate to your project directory and run claude to start. On first run, follow the browser prompts to authenticate.

Verify with:

claude --version
claude doctor     # detailed check

Minimum version: v2.1.295. The guard hooks set "onFailure": "block", introduced in that release, so that a guard which can't run blocks the command instead of letting it through (see Hooks). Features noted with a later version elsewhere in this README are optional.

Full documentation: code.claude.com/docs/en/setup

Optional Dependencies

Some components require additional tools. Install only what you need:

DependencyRequired byInstall
Node.js 18+context7, playwright MCP serversnodejs.org
Python >= 3.10 + uvpostgres, docker MCP serversdocs.astral.sh/uv
Dockerdocker MCP serverdocker.com
PostgreSQLpostgres MCP serverRunning instance (local or remote)
jqall six hooks — each one parses its payload and builds its response with itjqlang.github.io/jq
bubblewrap + socatBash sandbox on Linux/WSL2 only (macOS needs nothing; native Windows unsupported)your package manager
RTKtoken optimization (recommended)install guide

npx comes with Node.js. uvx comes with uv. No additional installs needed beyond the base tools.

Token savings tip: RTK (Rust Token Killer) (v0.43.0+) is a CLI proxy that reduces token consumption by 60-90% on common dev commands (git, tests, build, lint). Run rtk init -g to install a hook that automatically optimizes all shell commands in Claude Code sessions, then rtk gain to see per-command and session token savings.

Project Structure

claude-code-python-setup/
├── .claude/
│   ├── agents/              # Specialized subagents
│   │   ├── architect.md
│   │   ├── code-architect.md
│   │   ├── code-explorer.md
│   │   ├── code-reviewer.md
│   │   ├── comment-analyzer.md
│   │   ├── database-reviewer.md
│   │   ├── planner.md
│   │   ├── pr-test-analyzer.md
│   │   ├── refactor-cleaner.md
│   │   ├── security-reviewer.md
│   │   ├── silent-failure-hunter.md
│   │   ├── tdd-guide.md
│   │   └── type-design-analyzer.md
│   ├── commands/            # Slash commands (/command-name)
│   │   ├── build-fix.md
│   │   ├── clean-gone.md
│   │   ├── commit.md
│   │   ├── commit-push-pr.md
│   │   ├── feature-dev.md
│   │   ├── notebook-review.md
│   │   ├── orchestrate.md
│   │   ├── review-pr.md
│   │   ├── revise-claude-md.md
│   │   └── test-coverage.md
│   ├── hooks/                # Deterministic guardrails
│   │   ├── lib/
│   │   │   └── command-text.sh  # Strips heredoc / here-string bodies before matching
│   │   ├── session-start.sh  # Check uv env (.venv, lockfile) at session start
│   │   ├── guard-secrets.sh  # Block prompts containing hardcoded secrets
│   │   ├── enforce-uv.sh     # Rewrite bare python/py/pytest to uv run, block pip
│   │   ├── protect-main.sh   # Block force push, push to main, broad rm -rf / Remove-Item
│   │   ├── auto-lint.sh      # Auto-format Python files with ruff after edits
│   │   └── verify.sh         # Run ruff + pytest on Stop; block until green
│   ├── rules/                # Modular coding standards
│   │   ├── api-patterns.md   # FastAPI/Pydantic (path-scoped)
│   │   ├── architecture.md
│   │   ├── compaction.md
│   │   ├── documentation.md
│   │   ├── exception-handling.md
│   │   ├── git-workflow.md
│   │   ├── project-structure.md
│   │   ├── python-idioms.md
│   │   ├── security.md
│   │   └── testing.md
│   ├── settings.json          # Project-level hooks, permissions, status line
│   ├── statusline.py          # Status line script (Python, cross-platform)
│   └── skills/                # Reference docs and scripts
│       ├── api-design/
│       ├── claude-api/
│       ├── claude-automation-recommender/
│       ├── claude-md-improver/
│       ├── database-migrations/
│       ├── deployment-patterns/
│       ├── django-patterns/
│       ├── django-security/
│       ├── django-tdd/
│       ├── django-verification/
│       ├── doc-coauthoring/
│       ├── docker-patterns/
│       ├── docx/
│       ├── fastapi-patterns/
│       ├── frontend-design/
│       ├── mcp-builder/
│       ├── pdf/
│       ├── playground/
│       ├── postgres-patterns/
│       ├── pptx/
│       ├── skill-creator/
│       ├── webapp-testing/
│       └── xlsx/
├── .github/
│   ├── ISSUE_TEMPLATE/      # Bug report and feature request forms
│   ├── dependabot.yml       # Weekly grouped bumps for Actions and uv deps
│   ├── pull_request_template.md
│   └── workflows/
│       └── ci.yml           # Lint, shellcheck, hook tests on every PR
├── mcp_config/
│   ├── linux_mac.mcp.json   # MCP server config (Linux/Mac)
│   └── windows.mcp.json     # MCP server config (Windows)
├── tests/
│   ├── conftest.py          # Fixtures that run a hook against a payload
│   ├── hook_harness.py      # HookResult and payload builders
│   └── unit/                # One file per hook, asserting its decisions
├── .env.example             # Environment variables template
├── .gitattributes           # Force *.sh to LF so hooks run on Windows
├── .gitignore
├── .python-version          # Python version pin for uv
├── CHANGELOG.md             # Version history (Keep a Changelog format)
├── CLAUDE.md                # Project instructions (< 200 lines, imports rules)
├── CODE_OF_CONDUCT.md       # Contributor Covenant 2.1
├── CONTRIBUTING.md          # How to contribute, setup, PR workflow
├── LICENSE                  # MIT License
├── pyproject.toml           # Project metadata, ruff and pytest config
├── README.md
└── SECURITY.md              # Vulnerability reporting policy

Setup

1. Copy the .claude folder

Copy the .claude/ directory and CLAUDE.md into the root of your project.

Then open CLAUDE.md and replace the `<Y

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • .claude/skills/api-design/SKILL.md13 KB655d730e6449upstream ↗
    ---
    name: api-design
    description: REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning.
    metadata:
      origin: ECC
    ---
    
    # API Design Patterns
    
    Conventions and best practices for designing consistent, developer-friendly REST APIs.
    
    ## When to Activate
    
    - Designing new API endpoints
    - Reviewing existing API contracts
    - Adding pagination, filtering, or sorting
    - Implementing error handling for APIs
    - Planning API versioning strategy
    - Building public or partner-facing APIs
    
    ## Resource Design
    
    ### URL Structure
    
    ```
    # Resources are nouns, plural, lowercase, kebab-case
    GET    /api/v1/users
    GET    /api/v1/users/:id
    POST   /api/v1/users
    PUT    /api/v1/users/:id
    PATCH  /api/v1/users/:id
    DELETE /api/v1/users/:id
    
    # Sub-resources for relationships
    GET    /api/v1/users/:id/orders
    POST   /api/v1/users/:id/orders
    
    # Actions that don't map to CRUD (use verbs sparingly)
    POST   /api/v1/orders/:id/cancel
    POST   /api/v1/auth/login
    POST   /api/v1/auth/refresh
    ```
    
    ### Naming Rules
    
    ```
    # GOOD
    /api/v1/team-members          # kebab-case for multi-word resources
    /api/v1/orders?status=active  # query params for filtering
    /api/v1/users/123/orders      # nested resources for ownership
    
    # BAD
    /api/v1/getUsers              # verb in URL
    /api/v1/user                  # singular (use plural)
    /api/v1/team_members          # snake_case in URLs
    /api/v1/users/123/getOrders   # verb in nested resource
    ```
    
    ## HTTP Methods and Status Codes
    
    ### Method Semantics
    
    | Method | Idempotent | Safe | Use For |
    |--------|-----------|------|---------|
    | GET | Yes | Yes | Retrieve resources |
    | POST | No | No | Create resources, trigger actions |
    | PUT | Yes | No | Full replacement of a resource |
    | PATCH | No* | No | Partial update of a resource |
    | DELETE | Yes | No | Remove a resource |
    
    *PATCH can be made idempotent with proper implementation
    
    ### Status Code Reference
    
    ```
    # Success
    200 OK                    — GET, PUT, PATCH (with response body)
    201 Created               — POST (include Location header)
    204 No Content            — DELETE, PUT (no response body)
    
    # Client Errors
    400 Bad Request           — Validation failure, malformed JSON
    401 Unauthorized          — Missing or invalid authentication
    403 Forbidden             — Authenticated but not authorized
    404 Not Found             — Resource doesn't exist
    409 Conflict              — Duplicate entry, state conflict
    422 Unprocessable Entity  — Semantically invalid (valid JSON, bad data)
    429 Too Many Requests     — Rate limit exceeded
    
    # Server Errors
    500 Internal Server Error — Unexpected failure (never expose details)
    502 Bad Gateway           — Upstream service failed
    503 Service Unavailable   — Temporary overload, include Retry-After
    ```
    
    ### Common Mistakes
    
    ```
    # BAD: 200 for everything
    { "status": 200, "success": false, "error": "Not found" }
    
    # GOOD: Use HTTP status codes semantically
    HTTP/1.1 404 Not Found
    { "error": { "code": "not_found", "message": "User not found" } }
    
    # BAD: 500 for validation errors
    # GOOD: 400 or 422 with field-level details
    
    # BAD: 200 for created resources
    # GOOD: 201 with Location header
    HTTP/1.1 201 Created
    Location: /api/v1/users/abc-123
    ```
    
    ## Response Format
    
    ### Success Response
    
    ```json
    {
      "data": {
        "id": "abc-123",
        "email": "[email protected]",
        "name": "Alice",
        "created_at": "2025-01-15T10:30:00Z"
      }
    }
    ```
    
    ### Collection Response (with Pagination)
    
    ```json
    {
      "data": [
        { "id": "abc-123", "name": "Alice" },
        { "id": "def-456", "name": "Bob" }
      ],
      "meta": {
        "total": 142,
        "page": 1,
        "per_page": 20,
        "total_pages": 8
      },
      "links": {
        "self": "/api/v1/users?page=1&per_page=20",
        "next": "/api/v1/users?page=2&per_page=20",
        "last": "/api/v1/users?page=8&per_page=20"
      }
    }
    ```
    
    ### Error Response
    
    ```json
    {
      "error": {
        "code": "validation_error",
        "message": "Request validation failed",
        "details": [
          {
            "field": "email",
            "message": "Must be a valid email address",
            "code": "invalid_format"
          },
          {
            "field": "age",
            "message": "Must be between 0 and 150",
            "code": "out_of_range"
          }
        ]
      }
    }
    ```
    
    ### Response Envelope Variants
    
    ```typescript
    // Option A: Envelope with data wrapper (recommended for public APIs)
    interface ApiResponse<T> {
      data: T;
      meta?: PaginationMeta;
      links?: PaginationLinks;
    }
    
    interface ApiError {
      error: {
        code: string;
        message: string;
        details?: FieldError[];
      };
    }
    
    // Option B: Flat response (simpler, common for internal APIs)
    // Success: just return the resource directly
    // Error: return error object
    // Distinguish by HTTP status code
    ```
    
    ## Pagination
    
    ### Offset-Based (Simple)
    
    ```
    GET /api/v1/users?page=2&per_page=20
    
    # Implementation
    SELECT * FROM users
    ORDER BY created_at DESC
    LIMIT 20 OFFSET 20;
    ```
    
    **Pros:** Easy to implement, supports "jump to page N"
    **Cons:** Slow on large offsets (OFFSET 100000), inconsistent with concurrent inserts
    
    ### Cursor-Based (Scalable)
    
    ```
    GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
    
    # Implementation
    SELECT * FROM users
    WHERE id > :cursor_id
    ORDER BY id ASC
    LIMIT 21;  -- fetch one extra to determine has_next
    ```
    
    ```json
    {
      "data": [...],
      "meta": {
        "has_next": true,
        "next_cursor": "eyJpZCI6MTQzfQ"
      }
    }
    ```
    
    **Pros:** Consistent performance regardless of position, stable with concurrent inserts
    **Cons:** Cannot jump to arbitrary page, cursor is opaque
    
    ### When to Use Which
    
    | Use Case | Pagination Type |
    |----------|----------------|
    | Admin dashboards, small datasets (<10K) | Offset |
    | Infinite scroll, feeds, large datasets | Cursor |
    | Public APIs | Cursor (default) with offset (optional) |
    | Search results | Offset (users expect page numbers) |
    
    ## Filtering, Sorting, and Search
    
    ### Filtering
    
    ```
    # Simple equality
    GET /api/v1/orders?status=active&customer_id=abc-123
    
    # Comparison operators (use bracket notation)
    GET /api/v1/products?price[gte]=10&price[lte]=100
    GET /api/v1/orders?created_at[after]=2025-01-01
    
    # Multiple values (comma-separated)
    GET /api/v1/products?category=electronics,clothing
    
    # Nested fields (dot notation)
    GET /api/v1/orders?customer.country=US
    ```
    
    ### Sorting
    
    ```
    # Single field (prefix - for descending)
    GET /api/v1/products?sort=-created_at
    
    # Multiple fields (comma-separated)
    GET /api/v1/products?sort=-featured,price,-created_at
    ```
    
    ### Full-Text Search
    
    ```
    # Search query parameter
    GET /api/v1/products?q=wireless+headphones
    
    # Field-specific search
    GET /api/v1/users?email=alice
    ```
    
    ### Sparse Fieldsets
    
    ```
    # Return only specified fields (reduces payload)
    GET /api/v1/users?fields=id,name,email
    GET /api/v1/orders?fields=id,total,status&include=customer.name
    ```
    
    ## Authentication and Authorization
    
    ### Token-Based Auth
    
    ```
    # Bearer token in Authorization header
    GET /api/v1/users
    Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
    
    # API key (for server-to-server)
    GET /api/v1/data
    X-API-Key: sk_live_...
    ```
    
    ### Authorization Patterns
    
    ```typescript
    // Resource-level: check ownership
    app.get("/api/v1/orders/:id", async (req, res) => {
      const order = await Order.findById(req.params.id);
      if (!order) return res.status(404).json({ error: { code: "not_found" } });
      if (order.userId !== req.user.id) return res.status(403).json({ error: { code: "forbidden" } });
      return res.json({ data: order });
    });
    
    // Role-based: check permissions
    app.delete("/api/v1/users/:id", requireRole("admin"), async (req, res) => {
      await User.delete(req.params.id);
      return res.status(204).send();
    });
    ```
    
    ## Rate Limiting
    
    ### Headers
    
    ```
    HTTP/1.1 200 OK
    X-RateLimit-Limit: 100
    X-RateLimit-Remaining: 95
    X-RateLimit-Reset: 1640000000
    
    # When exceeded
    HTTP/1.1 429 Too Many Requests
    Retry-After: 60
    {
      "error": {
        "code": "rate_limit_exceeded",
        "message": "Rate limit exceeded. Try again in 60 seconds."
      }
    }
    ```
    
    ### Rate Limit Tiers
    
    | Tier | Limit | Window | Use Case |
    |------|-------|--------|----------|
    | Anonymous | 30/min | Per IP | Public endpoints |
    | Authenticated | 100/min | Per user | Standard API access |
    | Premium | 1000/min | Per API key | Paid API plans |
    | Internal | 10000/min | Per service | Service-to-service |
    
    ## Versioning
    
    ### URL Path Versioning (Recommended)
    
    ```
    /api/v1/users
    /api/v2/users
    ```
    
    **Pros:** Explicit, easy to route, cacheable
    **Cons:** URL changes between versions
    
    ### Header Versioning
    
    ```
    GET /api/users
    Accept: application/vnd.myapp.v2+json
    ```
    
    **Pros:** Clean URLs
    **Cons:** Harder to test, easy to forget
    
    ### Versioning Strategy
    
    ```
    1. Start with /api/v1/ — don't version until you need to
    2. Maintain at most 2 active versions (current + previous)
    3. Deprecation timeline:
       - Announce deprecation (6 months notice for public APIs)
       - Add Sunset header: Sunset: Sat, 01 Jan 2026 00:00:00 GMT
       - Return 410 Gone after sunset date
    4. Non-breaking changes don't need a new version:
       - Adding new fields to responses
       - Adding new optional query parameters
       - Adding new endpoints
    5. Breaking changes require a new version:
       - Removing or renaming fields
       - Changing field types
       - Changing URL structure
       - Changing authentication method
    ```
    
    ## Implementation Patterns
    
    ### TypeScript (Next.js API Route)
    
    ```typescript
    import { z } from "zod";
    import { NextRequest, NextResponse } from "next/server";
    
    const createUserSchema = z.object({
      email: z.string().email(),
      name: z.string().min(1).max(100),
    });
    
    export async function POST(req: NextRequest) {
      const body = await req.json();
      const parsed = createUserSchema.safeParse(body);
    
      if (!parsed.success) {
        return NextResponse.json({
          error: {
            code: "validation_error",
            message: "Request validation failed",
            details: parsed.error.issues.map(i => ({
              field: i.path.join("."),
              message: i.message,
              code: i.code,
            })),
          },
        }, { status: 422 });
      }
    
      const user = await createUser(parsed.data);
    
      return NextResponse.json(
        { data: user },
        {
          status: 201,
          headers: { Location: `/api/v1/users/${user.id}` },
        },
      );
    }
    ```
    
    ### Python (Django REST Framework)
    
    ```python
    from rest_framework import serializers, viewsets, status
    from rest_framework.response import Response
    
    class CreateUserSerializer(serializers.Serializer):
        email = serializers.EmailField()
        name = serializers.CharField(max_length=100)
    
    class UserSerializer(serializers.ModelSerializer):
        class Meta:
            model = User
            fields = ["id", "email", "name", "created_at"]
    
    class UserViewSet(viewsets.ModelViewSet):
        serializer_class = UserSerializer
        permission_classes = [IsAuthenticated]
    
        def get_serializer_class(self):
            if self.action == "create":
                return CreateUserSerializer
            return UserSerializer
    
        def create(self, request):
            serializer = CreateUserSerializer(data=request.data)
            serializer.is_valid(raise_exception=True)
            user = UserService.create(**serializer.validated_data)
            return Response(
                {"data": UserSerializer(user).data},
                status=status.HTTP_201_CREATED,
                headers={"Location": f"/api/v1/users/{user.id}"},
            )
    ```
    
    ### Go (net/http)
    
    ```go
    func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
        var req CreateUserRequest
        if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
            writeError(w, http.StatusBadRequest, "invalid_json", "Invalid request body")
            return
        }
    
        if err := req.Validate(); err != nil {
            writeError(w, http.StatusUnprocessableEntity, "validation_error", err.Error())
            return
        }
    
        user, err := h.service.Create(r.Context(), req)
        if err != nil {
            switch {
            case errors.Is(err, domain.ErrEmailTaken):
                writeError(w, http.StatusConflict, "email_taken", "Email already registered")
            default:
                writeError(w, http.StatusInternalServerError, "internal_error", "Internal error")
            }
            return
        }
    
        w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID))
        writeJSON(w, http.StatusCreated, map[string]any{"data": user})
    }
    ```
    
    ## API Design Checklist
    
    Before shipping a new endpoint:
    
    - [ ] Resource URL follows naming conventions (plural, kebab-case, no verbs)
    - [ ] Correct HTTP method used (GET for reads, POST for creates, etc.)
    - [ ] Appropriate status codes returned (not 200 for everything)
    - [ ] Input validated with schema (Zod, Pydantic, Bean Validation)
    - [ ] Error responses follow standard format with codes and messages
    - [ ] Pagination implemented for list endpoints (cursor or offset)
    - [ ] Authentication required (or explicitly marked as public)
    - [ ] Authorization checked (user can only access their own resources)
    - [ ] Rate limiting configured
    - [ ] Response does not leak internal details (stack traces, SQL errors)
    - [ ] Consistent naming with existing endpoints (camelCase vs snake_case)
    - [ ] Documented (OpenAPI/Swagger spec updated)
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/skateddu-claude-code-python-setup-claude-skills-api-design.md

// REPO STATS

28 stars
0 open issues
Last commit: 14d ago