fastapi-conventions/README.md

FastAPI Conventions

Descriptive first, prescriptive second. This repo captures how mature FastAPI-adjacent codebases structure web services, then distills the conventions worth following.

Use this repo for framework and service-boundary concerns that do not belong in a language-level Python patterns repo.

Structure

• patterns/ — route, dependency, schema, persistence, error, and testing conventions
• comparison/ — where FastAPI conventions differ from broader Python patterns
• sources/ — upstream notes, code excerpts, and rationale
• PROCESS.md — the repeatable extraction/refinement workflow used to build this repo

Current source base

Primary upstreams mined so far:

• fastapi/fastapi
• encode/starlette
• pydantic/pydantic
• encode/httpx
• fastapi-users/fastapi-users
• fastapi/full-stack-fastapi-template

Why this mix works:

• FastAPI: router composition, dependencies, semantic exceptions, override-based testing seams
• Starlette: lifespan, middleware, exception-layer mechanics, application assembly
• Pydantic: request/response model boundaries and validation/serialization caveats
• HTTPX: ASGI and transport-based testing seams
• FastAPI Users: dependency-driven auth and router factory patterns
• Full-stack FastAPI Template: real service module structure, session/auth wiring, and schema transitions

Current convention set

• patterns/routes.md
• patterns/dependencies.md
• patterns/pydantic-boundaries.md
• patterns/errors.md
• patterns/persistence.md
• patterns/testing.md
• comparison/fastapi-vs-python.md

What belongs here

Examples:

• thin route handlers vs embedded business logic
• request/response schema boundaries
• dependency injection shape and lifetime
• error envelope and exception translation
• app startup/shutdown and resource wiring
• sync/async boundaries at the HTTP layer

What does not belong here

Do not duplicate generic Python rules unless FastAPI deliberately bends them. Link back to python-patterns instead.

Reviewing this repo

Recommended review order:

1. README.md
2. PROCESS.md
3. sources/*.md for evidence quality
4. patterns/*.md for synthesis quality
5. comparison/*.md for split-of-concerns clarity

Questions to ask during review:

• Is the guidance actually FastAPI/service-boundary specific?
• Are framework seams described where the framework really owns behavior?
• Are testing and dependency claims grounded in real source and tests?
• Are caveats preserved instead of over-generalized?

Core rule

Do not write convention docs from memory. First collect repeated upstream examples with file:line citations, then synthesize the convention.