/fastapi

name: fastapi
description: Apply when building FastAPI endpoints, Pydantic models, or async APIs. Covers routing, dependency injection, error handling, testing, and OpenAPI hygiene.
license: MIT
version: 1.0.0
tokens_target: 2000
triggers:
  - fastapi endpoint
  - pydantic model
  - async api
loads_after:
  - python
supersedes: []

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

2. **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

3. **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.

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

5. **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.

6. **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.

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

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

9. **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.

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

11. **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.

12. **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.

13. **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.

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

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

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

17. **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.

18. **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`