| 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
- Classify each endpoint as collection, item, or nested resource.
- Verify verb-to-action mapping.
- Verify status code and error semantics.
- Verify Pydantic schema quality and response model clarity.
- Verify DI and layer boundaries.
- Verify authn/authz and least-privilege behavior.
- Apply checklist and report material issues first.
Output style
When asked to design or review APIs, respond concisely with:
- Endpoint proposal (route + method list).
- Contract notes (request/response + validation).
- Security checks (authn/authz + sensitive data handling).
- Checklist verdict (pass/fail highlights).
- Top fixes in priority order.
Additional resources