Fastapi REST API Design
Developmentfastapi-rest-api-designFastapi REST API Design is an Agent Skill for development published in the open-edge-platform/anomalib repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/open-edge-platform/anomalib/blob/HEAD/.agents/skills/fastapi-rest-api-design/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/fastapi-rest-api-design, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
GETread,POSTcreate,PUTfull replace,PATCHpartial update,DELETEremove. - Return
201on create,200on standard success, and204when 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
- Checklist: REST_API_CHECKLIST.md