/fastapi

name: fastapi
description: Use when building APIs with FastAPI. Covers dependency injection, Pydantic v2 validation, async database access, authentication, background tasks, and testing. Trigger on "fastapi endpoint is slow under load", "set up depends for the db session", "pydantic v2 validation error", "test my fastapi app". Do not use for API contract decisions like pagination or versioning — see the api-design skill.
metadata:
  category: backend
  version: 1.0.0
  tags: [fastapi, python, pydantic, async, api]

FastAPI

Purpose

Build FastAPI services that use the framework's strengths — declarative validation and dependency injection — without falling into its two standard traps: blocking calls inside `async def`, and business logic in the route handler.

When to Use

• Building or reviewing a FastAPI application.
• Structuring dependencies, authentication, and database sessions.
• Diagnosing latency that appears only under concurrency.
• Writing tests for FastAPI endpoints.

Capabilities

• Route and router organization.
• Pydantic v2 models for request, response, and settings.
• Dependency injection with scoped lifecycles.
• Async SQLAlchemy sessions, correctly scoped per request.
• Authentication and authorization dependencies.
• Testing with `httpx.AsyncClient` and dependency overrides.

Inputs

• The API contract and the data layer.
• Whether the workload is I/O-bound (nearly always) or CPU-bound.

Outputs

• Thin route handlers delegating to service functions.
• Response models that control exactly what is serialized.
• A test suite that overrides dependencies rather than mocking internals.

Workflow

1. **Define the schemas** — Separate request, response, and internal models. Never return an ORM object directly; a `response_model` is your defense against leaking a password hash. 2. **Build the dependencies** — Database session, current user, feature flags. These are the injection points that make the app testable. 3. **Keep handlers thin** — Parse, authorize, delegate, return. Business logic lives in a service module that knows nothing about HTTP. 4. **Get async right** — In an `async def` handler, every I/O call must be awaited. A blocking call there stalls the entire event loop, not just that request. 5. **Test through the app** — `httpx.AsyncClient` with `app.dependency_overrides` gives you real routing, real validation, and a fake database.

Best Practices

• A blocking call inside `async def` (a sync DB driver, `requests`, `time.sleep`) blocks every concurrent request on that worker. If a handler must call blocking code, define it as `def` — FastAPI runs it in a thread pool.
• Always set `response_model`. Without it, whatever your service returns is what the client sees, including fields you added last week.
• Use `Annotated[Session, Depends(get_session)]` — it keeps signatures readable and reusable.
• Validate settings with `pydantic-settings` at startup. Fail to boot on a bad config rather than at 3am on the first request that touches it.
• `BackgroundTasks` runs in the same process and dies with it. For anything that must not be lost, use a real queue.
• Mount routers by domain, not by HTTP verb.

Examples

**Dependency-injected handler and an overridable test:**

from typing import Annotated
from fastapi import APIRouter, Depends, HTTPException, status

router = APIRouter(prefix="/orders", tags=["orders"])

SessionDep = Annotated[AsyncSession, Depends(get_session)]
CurrentUser = Annotated[User, Depends(get_current_user)]


@router.post("", response_model=OrderRead, status_code=status.HTTP_201_CREATED)
async def create_order(
    payload: OrderCreate,
    session: SessionDep,
    user: CurrentUser,
) -> Order:
    try:
        return await orders.place(session, customer_id=user.id, items=payload.items)
    except InsufficientInventory as e:
        raise HTTPException(status.HTTP_409_CONFLICT, detail=str(e)) from e

@pytest.fixture
async def client(session: AsyncSession) -> AsyncIterator[AsyncClient]:
    app.dependency_overrides[get_session] = lambda: session
    app.dependency_overrides[get_current_user] = lambda: User(id="usr_test")
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as c:
        yield c
    app.dependency_overrides.clear()

Notes

• Pydantic v2 is roughly an order of magnitude faster than v1 on validation, but `Config` classes, validators, and `.dict()` all changed. Do not mix idioms.
• `@lru_cache` on a settings factory is the standard way to make configuration a singleton dependency.
• FastAPI's generated OpenAPI schema is only as good as your response models and status codes. Treat the generated docs as a review artifact.