Sub-Skill: FastAPI

Purpose: Prevent common FastAPI and Pydantic mistakes. Apply these rules whenever writing or reviewing FastAPI route handlers, Pydantic schemas, or async API code.

Rules

1. Always declare request and response bodies as Pydantic models — never use raw dict or Any for I/O. Reference: ERR-2026-025

1. Always use Pydantic v2 syntax (model_config, model_dump, model_validate) unless the project explicitly pins Pydantic v1 (pydantic<2 in requirements). Reference: ERR-2026-025

1. Always declare route handlers as async def unless the handler calls blocking I/O that cannot be awaited; use run_in_executor for blocking calls inside async handlers.

1. Always specify an explicit response_model on every route decorator so FastAPI filters and validates the response shape.

1. Always use status_code on the route decorator (@app.post("/items", status_code=201)) rather than constructing a Response object just to set the status.

1. Never raise bare Exception in route handlers; raise HTTPException with a meaningful status_code and detail string, or define a custom exception with an exception handler.

1. Always register exception handlers via @app.exception_handler(MyError) for domain errors rather than catching them inside every route.

1. Use Depends() for shared logic (auth, DB sessions, pagination params) — never duplicate the same logic across multiple route functions.

1. Prefer APIRouter with a prefix and tags list to group related endpoints; register routers with app.include_router() rather than defining all routes on the app object.

1. Always configure CORS via CORSMiddleware with an explicit allow_origins list; never use allow_origins=["*"] in production.

1. Use the lifespan context manager (FastAPI ≥ 0.93) for startup/shutdown logic instead of the deprecated @app.on_event("startup") / @app.on_event("shutdown") decorators.

1. Always use BackgroundTasks (injected via Depends or as a route parameter) for fire-and-forget work; never asyncio.create_task inside a route without a lifecycle guard.

1. Avoid exposing internal field names in OpenAPI by setting model_config = ConfigDict(populate_by_name=True) and using alias or alias_generator when the wire format differs from the Python attribute name.

1. Use pydantic-settings (BaseSettings) for configuration; never read os.environ directly inside route handlers or dependency functions.

1. Always test FastAPI routes with TestClient (sync) or AsyncClient from httpx (async); never spin up a real server in unit tests.

1. Ensure path operation functions declare only the parameters they actually use; unused Request injections or stale Depends imports are dead code and confuse readers.

1. Before adding a new route, check whether an existing router already owns that resource prefix; adding routes to the wrong router breaks OpenAPI tag grouping.

1. Never store mutable state in module-level variables inside route modules; use dependency-injected singletons or app.state instead.

See also

• skills/python/SKILL.md
• skills/code-quality/SKILL.md