fastapi

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.