fastapi-api-patterns

name	fastapi-api-patterns
description	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.
metadata	{"author":"cds-snc"}

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 — distributed by TomeVault.