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