FastAPI
Overview
- FastAPI is a Python framework for building APIs, built on Starlette.
- Starlette is the web framework that provides FastAPI’s routing and web functionality.
- Pydantic validates and serializes data using Python type hints.
- ASGI (Asynchronous Server Gateway Interface) is a standard interface between asynchronous Python web applications and servers.
- Uvicorn is an ASGI server that runs FastAPI and Starlette applications and handles incoming connections.
Installation and Setup
Installation
Use uv to install FastAPI with its standard dependencies, including the FastAPI CLI and Uvicorn:
uv add "fastapi[standard]"Creating an application
Create main.py in the project root or ./app directory:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}- 1
- Creates the ASGI application that receives requests.
- 2
-
Registers a handler function for
GET /; its return value is sent as JSON.
Configure and run
Add the application entrypoint to pyproject.toml so the FastAPI CLI knows where to find it:
[tool.fastapi]
entrypoint = "main:app"- 1
-
main:appmeans the objectappin the Python modulemain(main.py). For an application inapp/main.py, useapp.main:appinstead.
Run from the project root:
uv run fastapi dev # development: automatic reload, localhost only
uv run fastapi run # production mode: no reload, listens on 0.0.0.0Routing and Path Operations
HTTP Methods and Routes
Routes: A path operation connects an HTTP method and a URL path to a handler function. The same path can have different handlers for different methods.
Routers: Use APIRouter to group related routes:
from fastapi import APIRouter, FastAPI
app = FastAPI()
router = APIRouter(prefix="/items", tags=["items"])
items = []
@router.get("/")
async def list_items():
return items
@router.post("/", status_code=201)
async def create_item():
new_item = {"id": len(items) + 1, "name": "Example", "price": 10.0}
items.append(new_item)
return new_item
app.include_router(router)- 1
-
Groups routes under
/itemswith a shared documentation tag; routers can also share dependencies. - 2
-
Handle
GET /items/. - 3
-
Handle
POST /items/;status_code=201sets the success response code. - 4
- Registers the router’s endpoints with the application. Routers can live in separate files: see the example file structure.
Other decorators include @router.put(...), @router.patch(...), and @router.delete(...); the same decorators are available directly on app. See HTTP methods.
FastAPI evaluates routes in declaration order: declare a fixed path like /users/me before /users/{user_id} so it is not captured as a user ID.
Handling requests
| Declaration | Read from |
|---|---|
Name appears in the route’s {braces} |
Path |
| Scalar type, such as str, int, or bool | Query string |
Pydantic model, dict, list |
JSON body |
Path and Query Parameters
Names in {braces} are taken from the path; other scalar function parameters are normally taken from the query string. Type hints control parsing and validation:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(
item_id: int,
q: str,
limit: int = 10,
details: bool = False,
):
return {"item_id": item_id, "q": q, "limit": limit, "details": details}- 1
-
item_idis a required path parameter, parsed as an integer. - 2
-
qis a required query parameter because it has no default. - 3
-
limitis an optional query parameter, parsed as an integer and defaulting to10. - 4
-
detailsis an optional query parameter, parsed as a boolean and defaulting toFalse.
To allow an omitted query parameter to be None, use e.g. q: str | None = None.
For additional constraints on parameter values, see Type Hints and Validation Constraints.
Request Data and Validation
Pydantic Models and Request Bodies
Declare a Pydantic model to receive a JSON request body. FastAPI parses the JSON, validates it, and passes a model instance to the handler:
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str = Field(min_length=1, max_length=80)
price: float = Field(gt=0)
description: str | None = None
tags: list[str] = Field(default_factory=list)
@app.post("/items", status_code=201)
async def create_item(item: Item):
return item.model_dump()- 1
-
Fields without defaults are required.
Fieldadds validation constraints and schema metadata. - 2
-
Allows a string or
None; the defaultNonealso allows the field to be omitted.str | Nonewithout a default would still require the field. - 3
-
Creates a new empty list when
tagsis omitted. Collections and nested Pydantic models are validated recursively. - 4
- A Pydantic model parameter is read from the request body, not the query string.
- 5
-
Access values with e.g.
item.name;model_dump()converts the model to a dictionary.
Example request body (send with Content-Type: application/json):
{"name": "Notebook", "price": 4.5, "tags": ["office"]}Type Hints and Validation Constraints
Type hints define accepted data types; Field (for Pydantic), Path, Query, and Body add constraints and documentation. Use Annotated to attach type-metadata that fastAPI uses for validation:
from typing import Annotated
from fastapi import Path, Query
@app.get("/items/{item_id}")
async def read_item(
item_id: Annotated[int, Path(ge=1)],
limit: Annotated[int, Query(ge=1, le=100)] = 10,
):
return {"item_id": item_id, "limit": limit}- 1
-
Path(ge=1)requires an integer greater than or equal to 1. - 2
-
Query(ge=1, le=100)restricts the query parameter to 1–100; its default remains10.
Common validation constraints:
| Constraint | Meaning | Example |
|---|---|---|
gt, ge |
Greater than / greater than or equal to | Field(gt=0) |
lt, le |
Less than / less than or equal to | Query(le=100) |
min_length, max_length |
Bounds on string or collection length | Field(min_length=1) |
pattern |
Regular expression for a string | Query(pattern=r"^[a-z]+$") |
For a scalar body value, use Body explicitly; otherwise FastAPI normally treats a scalar as a query parameter:
A single scalar body parameter normally expects the model’s fields directly: {"price": 4.5, "name": "notebook"}
from typing import Annotated
from fastapi import Body
@app.put("/items/{item_id}/price")
async def update_price(
item_id: int,
price: Annotated[float, Body(gt=0, embed=True)],
):
return {"item_id": item_id, "price": price}- 1
-
embed=Trueexpects{"price": 4.5}rather than a bare JSON number4.5.
Expected body: {"price": 4.5}.
Multiple body parameters are wrapped under their parameter names {"price": 4.5, "item": {"name": "Notebook", "item_id": 4}}.
from typing import Annotated
from fastapi import Body
from pydantic import BaseModel, Field
class Item(BaseModel):
name: str = Field(min_length=1, max_length=80)
price: float = Field(gt=0)
description: str | None = None
tags: list[str] = Field(default_factory=list)
@app.put("/items/{item_id}/price")
async def update_price(
item_id: int,
price: Annotated[float, Body(gt=0)],
item: Item,
):
return {"device price": item.price, "total price": price}Expected body: {"price": 4.5, "item": {"name": "Notebook", "price": 4.5, "tags": ["portable"]}}.
Forms and File Uploads
Use Form for form fields and File / UploadFile for uploaded files.
from typing import Annotated
from fastapi import File, Form, UploadFile
@app.post("/uploads")
async def upload_file(
file: Annotated[UploadFile, File()],
description: Annotated[str, Form(max_length=200)] = "",
):
contents = await file.read()
return {
"filename": file.filename,
"description": description,
"size_bytes": len(contents),
}- 1
-
UploadFileuses a spooled file (memory, then disk above a size threshold), so it can handle larger uploads without immediately loading them into memory. Access metadata withfile.filenameandfile.content_type.Annotated[bytes, File()]instead loads the entire file into memory;list[UploadFile]accepts multiple files. - 2
-
Reads a form field from the same request. Forms without files normally use
application/x-www-form-urlencoded; uploads usemultipart/form-data. - 3
-
Reads the entire file contents as
bytes, so this is suitable for small files. Decode text withcontents.decode("utf-8"). For large files, repeatedly callawait file.read(size)to process chunks instead of loading everything into memory. FastAPI closes files automatically at request cleanup.
Form/file parameters cannot share the same request body with ordinary JSON body parameters. Use form fields for accompanying data rather than expecting a separate JSON body.
Responses
Response Models and Serialization
response_model validates, documents, and filters output to the declared fields. FastAPI serializes models, dates, and UUIDs to JSON automatically:
from pydantic import BaseModel
class UserOut(BaseModel):
name: str
@app.get("/users/me", response_model=UserOut)
async def read_user():
return {"name": "Ada", "password_hash": "hidden"} # Only name is sent.A return annotation such as -> UserOut also use the response model (then the type of the response must be UserOut however); explicit response_model takes priority. Use response_model_exclude_none=True to omit None fields.
Custom and Streaming Responses
For custom responses, use classes from fastapi.responses: HTMLResponse, PlainTextResponse, RedirectResponse, or FileResponse(path, filename="download.csv").
from fastapi.responses import HTMLResponse, StreamingResponse
@app.get("/page", response_class=HTMLResponse)
async def page():
return "<h1>Hello</h1>"
@app.get("/stream")
async def stream():
return StreamingResponse(iter(["Hello\n", "World\n"]), media_type="text/plain")StreamingResponse accepts a sync or async iterator of chunks. Returning a Response directly (instead of FastAPI constructing it) bypasses response-model validation and serialization. Using response_class or responses in the decorator documents the format, but it does not restore validation.
Error Handling
HTTP Exceptions and Validation Errors
Raise, rather than return, HTTPException to stop a request:
from fastapi import HTTPException
@app.get("/items/{item_id}")
async def read_item(item_id: int):
if item_id != 1:
raise HTTPException(status_code=404, detail="Item not found")
return {"id": item_id}The error body is {"detail": "Item not found"}. FastAPI prodcues 422 automatically for invalid request data and 500 for invalid response data.
Custom Exception Handlers
Register a handler for an exception class to customize errors globally:
from fastapi import Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
@app.exception_handler(RequestValidationError)
async def validation_error(request: Request, exc: RequestValidationError):
return JSONResponse(status_code=422, content={"detail": "Invalid request data"})- 1
- FastAPI requires the two arguments request (that caused the error) and exc (provides details on the error).
Dependency Injection
Declaring and Reusing Dependencies
Depends calls a function and injects its result; dependencies can themselves depend on other dependencies:
from typing import Annotated
from fastapi import Depends, Query
def pagination(limit: Annotated[int, Query(ge=1, le=100)] = 10):
return {"limit": limit}
Pagination = Annotated[dict, Depends(pagination)]
@app.get("/items")
async def list_items(params: Pagination):
return params- 1
-
This is a type alias meaning: This value is a dictionary obtained by calling
pagination. It does not callpaginationdirectly. - 2
-
FastAPI calls pagination with the
limitparameter from the query string: Query:GET /items?limit=25. Response:{"limit": 25}.
Reuse the alias across endpoints. Results are cached per request by default (use_cache=False disables this).
Dependencies with Cleanup
Use a single yield and finally (or a context manager) to release resources even on errors:
from typing import Annotated, Literal, TextIO
from fastapi import Depends
def get_file(filename: str):
file = open(filename, encoding="utf-8")
try:
yield file
finally:
file.close()
@app.get("/files/{filename}")
def read_file(file: Annotated[TextIO, Depends(get_file)]):
return {"contents": file.read()}- 1
-
FastAPI reads
filenamefrom the route’s path, even though it is declared in the dependency. - 2
-
For
GET /files/data.txt, FastAPI callsget_file(filename="data.txt")and injects the yielded file intoread_file. Thefinallyblock closes it after use, including when the endpoint raises an exception.
Cleanup normally runs after the response is sent, including streaming; Depends(get_file, scope="function") cleans up before sending it.
Security
OAuth2, Bearer Tokens, and API Keys
Security helpers from fastapi.security extract credentials and add OpenAPI security schemes:
| Helper | Credentials |
|---|---|
OAuth2PasswordBearer(tokenUrl="token") |
Bearer token; documents an OAuth2 password token endpoint |
HTTPBearer() |
Authorization: Bearer <token> as an HTTPAuthorizationCredentials object |
APIKeyHeader(name="X-API-Key") |
API key from a header |
from typing import Annotated
from fastapi import Depends, FastAPI
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
app = FastAPI()
bearer = HTTPBearer()
BearerCredentials = Annotated[HTTPAuthorizationCredentials, Depends(bearer)]
@app.get("/auth-info")
async def auth_info(credentials: BearerCredentials):
return {"scheme": credentials.scheme}- 1
-
HTTPBearer()creates a dependency that extracts bearer credentials from theAuthorizationheader and adds a bearer security scheme to OpenAPI. It rejects missing or non-bearer credentials by default, but does not validate the token itself. - 2
-
HTTPAuthorizationCredentialsis the object holding the extracted authentication scheme and raw token. This alias tells FastAPI to callbearerand inject that object. - 3
-
credentials.schemecontains"Bearer";credentials.credentialscontains the raw token.
Client sends Authorization: Bearer <token> to this endpoint.
CORS
CORS controls which browser origins (scheme + host + port) can access the API:
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_credentials=True,
allow_methods=["GET", "POST"],
allow_headers=["Authorization", "Content-Type"],
)Application Lifecycle and Configuration
Lifespan Events
Use lifespan for shared resources: code before yield runs at startup, cleanup runs at shutdown.
from contextlib import asynccontextmanager
from fastapi import FastAPI
from httpx import AsyncClient
@asynccontextmanager
async def lifespan(app: FastAPI):
async with AsyncClient() as client:
app.state.http = client # Reuse a connection pool across requests.
yield
# The context manager closes the client on shutdown.
app = FastAPI(lifespan=lifespan)Access the client through request.app.state.http in a handler that accepts request: Request. Lifespan runs separately in each worker process.
Settings and Environment Variables
Install with uv add pydantic-settings. Settings are typed and validated; environment variables override .env values, which override defaults:
from functools import lru_cache
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_file=".env", env_prefix="APP_")
debug: bool = False
database_url: str # Required: APP_DATABASE_URL.
@lru_cache
def get_settings() -> Settings:
return Settings()- 1
- The cache avoids re-reading configuration on every request.
Inject with settings: Annotated[Settings, Depends(get_settings)]. Keep .env and secrets out of version control; use environment injection or a secret manager in production.
Middleware
Middleware wraps requests and responses:
from time import perf_counter
from fastapi import Request
from loguru import logger
@app.middleware("http") # <1>
async def log_timing(request: Request, call_next):
start = perf_counter()
response = await call_next(request)
logger.info("Request completed in {:.6f} seconds", perf_counter() - start)
return response- 1
- Middleware wraps all http requests for all routes and methods - but not websocket connections.
The last-added middleware runs first on requests and last on responses. Use app.add_middleware(...) for middleware classes, such as CORS.
Thread Safety
Since parallel workers can change the same state of your app, you need to avoid them from overwriting each others data by introducing locks:
from threading import Lock
from fastapi import FastAPI
@asynccontextmanager
async def lifespan(app: FastAPI):
app.state.dataset_store = DatasetStore()
yield
app = FastAPI(lifespan=lifespan)
class DatasetStore:
def __init__(self):
self.next_id: int = 0
self.datasets: dict[int, list[list[int | float]]] = {}
self.lock = Lock()
@app.post("/datasets", status_code=status.HTTP_201_CREATED)
def create_dataset(dataset: list[list[int | float]]) -> dict:
dataset_store = app.state.dataset_store
with dataset_store.lock:
dataset_id = dataset_store.next_id
dataset_store.datasets[dataset_id] = dataset- 1
- The datasets are stored in the app-state in this example (not for production use: only presisted in memory).
- 2
-
This is the lock-instance for the attributes (
next_idanddataset) of one instance (app.state.data_store) ofDataStore. - 3
- When creating a new dataset, the lock ensures that no other thread can change the variables. This way, the id-incrementation and dataset-appending together are one atomic operation.
Scope a lock for a single object’s attributes, to avoid threads from unnecessarily blocking each other.
Background Tasks
Use BackgroundTasks, if you want to send a response directly to the client (e.g. “received request. Here is your job_id.”) and run longer task in the background after the response is sent.
from fastapi import BackgroundTasks, FastAPI
app = FastAPI()
def write_log(message: str):
with open("events.log", "a", encoding="utf-8") as file:
file.write(message + "\n")
@app.post("/events", status_code=202)
async def record_event(message: str, background_tasks: BackgroundTasks):
background_tasks.add_task(write_log, message)
return {"message": "Event accepted"}- 1
-
A regular
deftask runs in a thread pool, suitable for blocking I/O. Anasync deftask is also supported, but must not perform blocking work on the event loop. - 2
-
FastAPI injects
BackgroundTasksautomatically; noDependsis needed. Here,messagecomes from the query string (e.g.POST /events?message=Hello). - 3
-
Registers the function and its arguments. Pass
write_log, notwrite_log(message), so it runs later rather than immediately. - 4
- Returns 202 Accepted without waiting for the task to finish; this does not confirm that the task succeeded.
Tasks run in the same application process, not a separate worker service, and can be lost on a crash or restart. Use a job queue such as Celery for heavy computation, retries, or durable jobs; BackgroundTasks does not provide job IDs or status tracking automatically.
Testing
Test Client and Async Tests
Install with uv add --dev pytest httpx. Tests call the app directly without starting a server; run with uv run pytest:
from fastapi.testclient import TestClient
from main import app
def test_root():
with TestClient(app) as client: # Context manager runs lifespan.
response = client.get("/")
assert response.status_code == 200
assert response.json() == {"message": "Hello World"}For tests that need await, use HTTPX’s async client and AnyIO’s pytest plugin (AnyIO is a FastAPI dependency):
import pytest
from httpx import ASGITransport, AsyncClient
from main import app
@pytest.fixture
def anyio_backend():
return "asyncio"
@pytest.mark.anyio
async def test_root_async():
async with AsyncClient(
transport=ASGITransport(app=app), base_url="http://test"
) as client:
response = await client.get("/")
assert response.status_code == 200ASGITransport does not run lifespan automatically. If startup resources are required, wrap the client in async with LifespanManager(app) from asgi-lifespan (uv add --dev asgi-lifespan).
Dependency Overrides
Map the original dependency function to a replacement, e.g. to swap settings, authentication, or database sessions:
from main import app, get_settings, Settings
def test_with_settings():
app.dependency_overrides[get_settings] = lambda: Settings(
database_url="sqlite://", debug=True
)
try:
with TestClient(app) as client:
assert client.get("/").status_code == 200
finally:
app.dependency_overrides.pop(get_settings, None)Only calls resolved through Depends are replaced, not direct function calls. Always restore overrides after tests; use an isolated test database rather than production data.
Deployment and Observability
ASGI Servers and Production Configuration
Serve the ASGI app with Uvicorn (or another ASGI server, such as Hypercorn):
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4- Never use
--reloadin production; it cannot be combined with--workers. - Workers are separate processes: memory, caches, ML models, and connection pools are duplicated. Choose the count based on memory and load; orchestrated containers often use one worker per replica.
- Put HTTPS termination/load balancing in front of the app and trust forwarded headers only from known proxies (
--proxy-headers --forwarded-allow-ips=...). Use--root-path /apiif a proxy strips that URL prefix. - Configure restarts, health/readiness checks, resource limits, and graceful shutdown. Run migrations once before workers start, not independently in each worker’s lifespan.