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

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

Boundary rubric: does this belong in `fastapi-conventions`?

Use this repo when the rule is mainly about the HTTP or app boundary: routes, Depends(...), request/response schemas, HTTP error meaning, lifespan, or ASGI-level testing.

Push it back to the sibling python-patterns repo when the rule would still make sense in a CLI, library, or batch job.

Quick check:

if FastAPI or Starlette owns the behavior, this repo should lead
if deleting the HTTP boundary leaves most of the rule intact, it is probably too generic for this repo
if the split is awkward, prefer the higher-level doc and cross-link rather than duplicating guidance

Core rule

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

1.9 KiB Raw Blame History