The Glossary of FastAPI

Core Concepts

FastAPI — A modern Python web framework for building APIs, built on top of Starlette (for the web parts) and Pydantic (for the data parts), designed around Python type hints as its central organizing idea.

ASGI (Asynchronous Server Gateway Interface) — The successor to WSGI, a standard interface between Python web servers and applications that supports asynchronous code, WebSockets, and long-lived connections — the foundation FastAPI is built on.

Starlette — The lightweight ASGI framework FastAPI is built on top of, providing the underlying routing, middleware, and request/response handling that FastAPI adds validation, serialization, and documentation on top of.

Pydantic — The data validation library FastAPI uses to define, parse, and validate request and response data using ordinary Python type hints and classes, raising clear errors automatically when data doesn't match.

Uvicorn — The ASGI server most commonly used to actually run a FastAPI application, translating incoming HTTP requests into calls against the app and sending responses back.

Type Hints as Contract — FastAPI's defining design choice: the same Python type annotations used for editor autocomplete and static checking are read at runtime to validate input, serialize output, and generate documentation — one declaration doing triple duty.

Path Operation — FastAPI's term for a function bound to a specific HTTP method and URL path (@app.get("/items/{id}")), the basic unit of an API's behavior.

Decorator (@app.get, @app.post, …) — The syntax used to register a function as the handler for a specific route and HTTP verb, one decorator per method FastAPI supports (GET, POST, PUT, DELETE, PATCH, and others).

Routing & Requests

Path Parameter — A dynamic segment of a URL (/items/{item_id}) captured and passed into the handler function, automatically validated and converted based on the function's type hint.

Query Parameter — A value passed after ? in a URL (/items?skip=0&limit=10), declared simply as a function argument that isn't part of the path — FastAPI infers it's a query parameter by elimination.

Request Body — Data sent in the body of a request (typically POST or PUT), declared as a Pydantic model argument in the handler, which FastAPI parses from JSON and validates automatically.

Pydantic Model (BaseModel) — A class inheriting from Pydantic's BaseModel that defines the expected shape of data — field names, types, and constraints — used throughout FastAPI to describe request bodies, response bodies, and nested data structures.

Response Model — The response_model parameter on a path operation, specifying the Pydantic model the output should conform to, letting FastAPI filter and serialize the return value automatically — even stripping out fields the handler returned but the schema doesn't include.

Status Code — The HTTP response code (200, 404, 422, and so on) a path operation returns, settable explicitly via status_code or raised through HTTPException.

HTTPException — FastAPI's built-in exception class for returning a specific HTTP error status and message from inside a path operation, the standard way to signal "not found," "unauthorized," and similar conditions.

Header / Cookie Parameters — Special parameter types (Header, Cookie) that let a handler declare it expects a value to arrive via request headers or cookies rather than the query string or body, validated the same way as any other parameter.

Form Data / File Upload — Special parameter types (Form, File, UploadFile) for handling traditional form submissions and uploaded files, as distinct from JSON request bodies.

Data Validation & Serialization

Field — A Pydantic function used inside a model to add extra validation and metadata to an individual attribute — bounds, default values, descriptions — beyond what the bare type hint expresses.

Validator — A method on a Pydantic model (traditionally @validator, now @field_validator in Pydantic v2) that runs custom validation logic on a field beyond simple type checking.

Serialization — The process of converting a Python object (like a Pydantic model or database row) into a JSON-compatible format for the HTTP response — handled automatically by FastAPI based on the declared response model.

422 Unprocessable Entity — The status code FastAPI returns automatically when incoming request data fails Pydantic validation, along with a JSON body detailing exactly which fields failed and why.

Nested Models — Pydantic models that contain other Pydantic models as fields, letting complex, hierarchical JSON structures be validated and documented as a single coherent schema.

Enum — Python's standard Enum class, commonly used in FastAPI to restrict a field or path parameter to a fixed set of allowed values, which also shows up as a dropdown in the generated docs.

Pydantic v1 vs v2 — The major rewrite of Pydantic (v2, released 2023) that reimplemented its validation core in Rust for significant performance gains, while changing parts of its API — a distinction that still matters when reading tutorials or debugging version-specific behavior.

Dependency Injection & Structure

Dependency Injection — FastAPI's system for declaring shared logic — database sessions, authentication checks, pagination parameters — as reusable functions that path operations request as parameters, rather than importing and calling directly.

Depends — The function used to mark a parameter as something FastAPI should resolve by calling another function first, the mechanism underlying FastAPI's dependency injection system.

Sub-dependency — A dependency that itself depends on another dependency, resolved automatically in the right order — letting complex setup logic (like "get the current authenticated user," which itself needs "get the database session") be composed from smaller pieces.

APIRouter — A class for grouping related path operations into a separate module, which can then be included into the main app with a shared prefix, tags, or dependencies — FastAPI's answer to organizing large applications across multiple files.

Middleware — A function that runs on every request and response passing through the app, used for cross-cutting concerns like logging, timing, or adding headers, registered with @app.middleware.

Lifespan Events (startup/shutdown) — Hooks that run code when the application starts up or shuts down — commonly used to open and close database connections or load ML models — handled through the lifespan context manager.

Async, Performance & Security

async def Path Operation — A path operation declared with async def rather than plain def, allowing it to await other coroutines (like async database calls) without blocking the event loop while waiting on I/O.

Sync Path Operation — A path operation declared with regular def, which FastAPI automatically runs in an external thread pool so that blocking code doesn't stall the whole async event loop — a deliberate design choice that lets both styles coexist safely.

Event Loop — The core mechanism, provided by Python's asyncio, that manages and schedules coroutines, letting a single thread handle many concurrent requests by switching between them whenever one is waiting on I/O.

OAuth2 / OAuth2PasswordBearer — FastAPI's built-in utilities for implementing OAuth2-based authentication flows, including extracting and validating bearer tokens from incoming requests.

Security Scheme — The general term for how FastAPI documents and enforces authentication and authorization requirements on a path operation, integrated with the auto-generated docs so protected endpoints show a lock icon and login flow.

CORS (Cross-Origin Resource Sharing) Middleware — Built-in Starlette middleware, commonly configured through FastAPI, that controls which external domains are allowed to make requests to the API from a browser.

Background Tasks — A FastAPI feature (BackgroundTasks) for running a function after a response has already been sent to the client, useful for work like sending an email or logging that shouldn't delay the response.

Documentation & Ecosystem

OpenAPI Schema — The machine-readable specification, automatically generated by FastAPI from the app's type hints and models, describing every path, parameter, and response — the source of truth the interactive docs are built from.

Swagger UI — The interactive API documentation, served automatically at /docs, generated from the OpenAPI schema, letting developers browse and test every endpoint directly from the browser.

ReDoc — An alternative, read-only API documentation interface, served automatically at /redoc, generated from the same OpenAPI schema as Swagger UI but with a different layout suited to reference reading.

SQLAlchemy / SQLModel — The most common ORMs paired with FastAPI for database access — SQLAlchemy being the long-established, general-purpose Python ORM, and SQLModel a newer library (by FastAPI's own author) that unifies SQLAlchemy models and Pydantic models into one class.

Alembic — A database migration tool commonly paired with SQLAlchemy in FastAPI projects, used to version and apply incremental changes to a database schema over time.

TestClient — A utility (built on httpx) for writing tests against a FastAPI app without running a real server, letting pytest send requests directly to the application in-process.

Pytest — The de facto standard testing framework used across the FastAPI ecosystem, typically paired with TestClient and, for async test cases, pytest-asyncio or anyio.

Uvicorn Workers / Gunicorn — The common production deployment pattern of running multiple Uvicorn worker processes (often managed by Gunicorn) to use multiple CPU cores, since a single async process still runs on one thread.

Taken together, this glossary tells a fairly compact story: FastAPI's whole design is an argument that Python's type hints — originally added just for editor tooling and static checkers — could also drive validation, serialization, and documentation at runtime, all from one declaration. Every term here traces back to that single decision. Pydantic models double as both parser and API contract; dependency injection exists so shared logic can be typed and validated the same way as request data; the entire interactive documentation layer is a byproduct of taking type hints seriously enough to build a framework around them. It's a smaller, younger story than The Glossary of Python it builds on — but it's really just that story's logical conclusion, taken as far as it will go.

*written with Claude Sonnet 5