fastapi-rest-api-design

# FastAPI REST API Design Use this skill when designing, implementing, or reviewing FastAPI REST endpoints. ## Purpose and scope This skill enforces practical REST design and FastAPI implementation quality: resource naming, HTTP semantics, schema quality, dependency boundaries, security checks, and concise review output. ## Core design rules ### Resource and path conventions - Use nouns in paths, not action verbs. - Use plural collection names such as `/projects`, `/users`. - Use stable item identifiers such as `/projects/{project_id}`. - Keep names lowercase and consistent. - Keep nesting shallow (typically max 2 levels), for example `/projects/{project_id}/models`. - Do not expose internal storage structure in public routes. ### HTTP methods and status semantics - Use `GET` read, `POST` create, `PUT` full replace, `PATCH` partial update, `DELETE` remove. - Return `201` on create, `200` on standard success, and `204` when no response body is needed. - Choose precise error codes (`400`, `401`, `403`, `404`, `409`, `422`, `500`) and avoid vague fallbacks. - Keep semantics consistent across related endpoints. ### Request/response contracts - Use JSON payloads for standard API requests/responses. - Use Pydantic models for request and response contracts. - Enforce explicit field constraints (enums, lengths, ranges, formats). - Prefer explicit response models for stable contracts. - Keep error response bodies consistent across endpoints. ### FastAPI architecture patterns - Organize routes by resource/domain with `APIRouter`. - Inject dependencies with `Depends(...)`; avoid hidden globals. - Keep handlers thin and move business logic into services/use-cases. - Raise domain exceptions in service layer and map to HTTP errors at API boundary. - Add explicit `responses={...}` metadata when custom errors must appear in OpenAPI docs. ### Security and operability - Enforce HTTPS in deployed environments. - Enforce authentication and authorization per route/use case. - Apply least-privilege checks for each resource operation. - Avoid exposing sensitive internals in error details. - Add filtering, sorting, and pagination for large collection endpoints. - Introduce versioning (for example `/v1/...`) before shipping breaking API changes. ## Review workflow 1. Classify each endpoint as collection, item, or nested resource. 2. Verify verb-to-action mapping. 3. Verify status code and error semantics. 4. Verify Pydantic schema quality and response model clarity. 5. Verify DI and layer boundaries. 6. Verify authn/authz and least-privilege behavior. 7. Apply checklist and report material issues first. ## Output style When asked to design or review APIs, respond concisely with: 1. Endpoint proposal (route + method list). 2. Contract notes (request/response + validation). 3. Security checks (authn/authz + sensitive data handling). 4. Checklist verdict (pass/fail highlights). 5. Top fixes in priority order. ## Additional resources - Checklist: [REST_API_CHECKLIST.md](REST_API_CHECKLIST.md)