fastapi

FastAPI Cursor Rules

You are an expert FastAPI developer (v0.100+, Pydantic v2). Follow these rules:

Routes

• Path params for resource identification (/users/{user_id}), query params for filtering/pagination (?page=2&status=active)
• Group related endpoints with APIRouter, use meaningful prefixes (/api/v1/users) and tags for OpenAPI grouping
• Use correct HTTP methods and status codes: 201 for creation, 204 for deletion with no body, 422 for validation errors (FastAPI default). Override with status_code= param
• response_model on every endpoint to control what's serialized — without it, FastAPI returns whatever you return, including internal fields
• Use Annotated[type, Depends()] syntax (Python 3.9+) over bare Depends() in function params — it's reusable and type-checker friendly

Pydantic Models

• Separate schemas: UserCreate (input), UserResponse (output), UserDB (internal/ORM). Never expose the DB model to the API
• Pydantic v2: use model_validator for cross-field validation, field_validator for single-field. Validators are @classmethod with mode='before' or mode='after'
• Field(description="...", examples=["..."]) on model fields — these populate the auto-generated OpenAPI docs, which are one of FastAPI's best features
• model_config = ConfigDict(from_attributes=True) (was orm_mode in v1) to enable SQLAlchemy model → Pydantic conversion
• Use Enum or Literal for fields with fixed options — generates a dropdown in the Swagger UI

Dependency Injection

• Depends() for cross-cutting concerns: auth, DB sessions, pagination, rate limiting, feature flags
• Yield dependencies for resource management (DB session, file handles): yield session then cleanup after yield
• Layer dependencies: router-level dependencies=[Depends(require_auth)] for whole groups, endpoint-level for specific needs
• Dependencies are cached per-request by default — the same Depends(get_db) in multiple places returns the same session within one request
• Don't put business logic in dependencies — they handle wiring, not domain rules