fastapi-rest-api-design

name: fastapi-rest-api-design description: Designs and reviews REST APIs for FastAPI services using consistent resource naming, HTTP semantics, validation, security, and error handling patterns. Use for backend API tasks, endpoint design/refactors, or API review requests in FastAPI/Python projects.

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