# Fastapi API Patterns > Apply typed FastAPI route patterns with clean dependency boundaries, stable error mapping, and test coverage for success/failure paths. Use when this capability is needed. - Skill: `tomevault-io/fastapi-api-patterns` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/fastapi-api-patterns` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/fastapi-api-patterns/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/fastapi-api-patterns --- Use this skill when implementing or reviewing API endpoints. ## Core Rules 1. Keep transport concerns in router layers only. 2. Keep business logic in package services. 3. Use typed schemas at I/O boundaries. 4. Map domain/application errors to stable HTTP responses. 5. Ensure async-safe I/O boundaries. 6. Add or adjust tests for success and failure paths. ## Handler Shape - Prefer explicit request/response models. - Keep handlers orchestration-thin. - Inject dependencies through providers/dependencies rather than in-handler construction. ## Error Mapping - Do not return raw internal result envelopes from routes. - Normalize domain errors to consistent HTTP status codes and response detail shape. - Log contextual, non-sensitive metadata for failures. ## Forbidden Patterns - Business logic directly in route handlers. - Returning raw `OperationResult` objects from HTTP handlers. - Accessing `request.app.state` inside handlers when a dependency can be injected. - Broad exception catches that collapse distinct error classes. ## Test Matrix (Minimum) 1. Success response path with expected schema. 2. Failure mapping path (at least one domain/application error). 3. Dependency-driven path (auth/rate limit/permission branch where relevant). ## OpenAPI Minimum Metadata - Router includes exactly one tag. - Route includes a clear summary and/or description. - Route defines expected response mapping for non-2xx conditions. - Public request/response fields include descriptions. --- > Source: [cds-snc/sre-bot](https://github.com/cds-snc/sre-bot) — distributed by [TomeVault](https://tomevault.io).