02 · Middleware Wraps the Request Lifecycle
In the first tutorial, we followed this path:
Browser → HTTP request → FastAPI router → route function → HTTP response → browser
Today we add middleware:
Browser → HTTP request → middleware → router → route function → middleware → HTTP response → browser
Middleware sits around the application. It sees the request before the route runs, and it sees the response after the route runs.
That two-way behavior is the key idea.
Today’s application
Section titled “Today’s application”We’ll expand the product page from the first tutorial:
import timefrom uuid import uuid4
from fastapi import FastAPI, Requestfrom fastapi.responses import HTMLResponse
app = FastAPI()
@app.middleware("http")async def add_request_context(request: Request, call_next): request_id = str(uuid4()) request.state.request_id = request_id
start_time = time.perf_counter()
response = await call_next(request)
elapsed_ms = (time.perf_counter() - start_time) * 1000
response.headers["X-Request-ID"] = request_id response.headers["X-Process-Time-Ms"] = f"{elapsed_ms:.2f}"
return response
@app.get("/products/{product_id}", response_class=HTMLResponse)async def product_page(request: Request, product_id: int): request_id = request.state.request_id
return f""" <html> <body> <h1>Product {product_id}</h1> <p>Request ID: {request_id}</p> </body> </html> """If the browser requests:
http://127.0.0.1:8000/products/42it receives an HTML page containing the product number and a unique request ID.
The response also contains two custom HTTP headers:
X-Request-ID: 8f37f744-0c15-4edf-a773-b123d56659efX-Process-Time-Ms: 1.84Your actual values would be different.
The application still has two phases
Section titled “The application still has two phases”As before, we must distinguish:
- Application startup
- Request handling
The middleware decorator runs during startup:
@app.middleware("http")The middleware function itself runs during request handling:
async def add_request_context(request: Request, call_next):This is the same pattern we saw with routes.
The route decorator:
@app.get("/products/{product_id}")registers the route during startup.
The route function:
async def product_page(...):runs later when an appropriate request arrives.
Likewise, the middleware decorator registers middleware during startup, while the middleware function runs for every HTTP request.
The imports
Section titled “The imports”import timefrom uuid import uuid4These are standard Python-library imports.
We use time.perf_counter() to measure how long request processing takes.
We use uuid4() to generate a unique identifier for each request.
Then we import the framework objects:
from fastapi import FastAPI, Requestfrom fastapi.responses import HTMLResponseFastAPI creates the application.
Request represents an incoming HTTP request.
HTMLResponse tells FastAPI that the route returns HTML rather than ordinary JSON data.
Creating the application
Section titled “Creating the application”app = FastAPI()Python creates one FastAPI application object.
That object becomes the central registry for:
- Middleware
- Routes
- Exception handlers
- Application events
- OpenAPI configuration
The middleware and route decorators underneath modify this object during application startup.
Registering the middleware
Section titled “Registering the middleware”@app.middleware("http")This tells FastAPI:
Register the function immediately below as middleware for HTTP traffic.
The string "http" identifies the kind of traffic this middleware handles.
FastAPI can also support other communication types, such as WebSocket connections, but this particular function is for normal HTTP requests and responses.
The decorator registers:
add_request_contextas part of the request-processing pipeline.
The middleware will therefore run for requests such as:
GET /products/42It will also run for:
GET /docsand:
POST /loginand even for a path that does not exist:
GET /something-that-is-not-hereThis is an important difference between middleware and a route.
A route handles a specific method-and-path combination.
Middleware surrounds the whole HTTP application.
FastAPI defines middleware as code that receives every request before a path operation and every resulting response before it is returned. (FastAPI middleware documentation)
The middleware function
Section titled “The middleware function”async def add_request_context(request: Request, call_next):FastAPI provides this function with two arguments:
requestcall_next
These are very different objects.
The request object
Section titled “The request object”request: Requestrequest represents the incoming HTTP request.
It contains information such as:
request.methodrequest.urlrequest.headersrequest.cookiesrequest.clientrequest.stateFor our example request:
http://127.0.0.1:8000/products/42some conceptual values would be:
request.method# "GET"
request.url.path# "/products/42"The HTTP request arrived as network data. The server and framework turned that data into a Python Request object so your code can work with it conveniently.
The call_next function
Section titled “The call_next function”call_nextcall_next is a function FastAPI supplies to the middleware.
Conceptually, it means:
Pass this request deeper into the application and give me the response that comes back.
Calling it moves execution toward:
- Other middleware
- The router
- Dependencies
- The selected route function
- Response creation
Today’s application has only one custom middleware, so we can simplify its meaning to:
Continue to routing and execute the appropriate route.
But call_next is not the route function itself.
The middleware does not yet know whether /products/42 will be handled by product_page, another route, or a 404 response. It simply passes the request into the rest of the application.
Before the route runs
Section titled “Before the route runs”Everything above this line runs on the incoming side:
response = await call_next(request)Our first incoming operation is:
request_id = str(uuid4())Creating a UUID
Section titled “Creating a UUID”uuid4() returns a UUID object resembling:
UUID("8f37f744-0c15-4edf-a773-b123d56659ef")A UUID is designed to be practically unique.
The chance that two normal requests receive the same randomly generated UUID is so small that applications can safely treat these values as unique identifiers.
We convert the UUID object into a string:
str(uuid4())Now request_id contains ordinary Python text:
"8f37f744-0c15-4edf-a773-b123d56659ef"Why give every request an ID?
Imagine two users make requests at nearly the same time. Your server logs might contain:
Request startedDatabase query startedRequest startedDatabase query failedRequest completedWhich database query belongs to which request?
If each log entry includes a request ID, the sequence becomes traceable:
request=abc123 Request startedrequest=abc123 Database query startedrequest=xyz789 Request startedrequest=abc123 Database query failedrequest=xyz789 Request completedRequest IDs help connect activity across middleware, routes, services, database operations, and logs.
This becomes especially valuable in production.
Storing information on the request
Section titled “Storing information on the request”request.state.request_id = request_idThis line deserves careful attention.
request.state is a place where your application can attach information to this particular request.
We create an attribute named:
request_idand assign our UUID string to it.
Afterward:
request.state.request_idreturns the same value.
This is not global application state.
It belongs to the individual Request object. Another simultaneous request receives its own Request object and its own request ID.
Conceptually:
Request A└── state.request_id = "abc123"
Request B└── state.request_id = "xyz789"This lets middleware calculate or discover something once and make it available to later layers.
For example, middleware might attach:
- A request ID
- Tenant information
- Tracing information
- A locale
- Carefully validated request metadata
Authentication information is sometimes attached to the request too, although FastAPI dependencies are often a cleaner way to provide the current user to routes. We’ll examine that distinction later.
Starting the timer
Section titled “Starting the timer”start_time = time.perf_counter()time.perf_counter() returns a high-resolution timer value.
The number itself is not a normal clock time:
482150.183726It does not mean 4:21 PM or represent a calendar date.
Its purpose is to compare two readings.
We record one value before the rest of the application runs:
start_time = time.perf_counter()Later, we take another reading and subtract the first.
That difference tells us how much time passed.
The turning point: call_next
Section titled “The turning point: call_next”response = await call_next(request)This is the most important line in the middleware.
It divides the function into two sides:
# Incoming request siderequest_id = str(uuid4())request.state.request_id = request_idstart_time = time.perf_counter()
# Enter the rest of the applicationresponse = await call_next(request)
# Outgoing response sideelapsed_ms = ...response.headers[...] = ...return responseYou can picture the middleware as a wrapper:
Middleware begins Application runsMiddleware finishesOr, more specifically:
add_request_context begins router selects product_page product_page runs product_page returns HTML FastAPI builds an HTMLResponseadd_request_context receives that responseadd_request_context modifies the responseadd_request_context returns the responseWhy await appears here
Section titled “Why await appears here”call_next(request) represents work that may not finish immediately.
The application may need to:
- Run dependencies
- Wait for database activity
- Call external services
- Execute the route
- Build the response
The middleware therefore pauses at:
await call_next(request)While that work is pending, the event loop may allow the server to make progress on other requests.
When the downstream application finishes, call_next() returns a response, and execution resumes inside the middleware.
The result is stored here:
response = ...The middleware now possesses the response before it has been sent to the browser.
What happens inside call_next
Section titled “What happens inside call_next”The request passed inward is still:
GET /products/42FastAPI’s router examines the registered routes and finds:
@app.get("/products/{product_id}", response_class=HTMLResponse)The method matches GET.
The path pattern matches /products/42.
FastAPI extracts:
"42"from the path.
Because the route declares:
product_id: intFastAPI converts the text into the Python integer:
42The route also declares:
request: RequestFastAPI recognizes the type and supplies the current Request object.
FastAPI therefore makes the conceptual call:
await product_page( request=current_request, product_id=42,)Reading middleware data inside the route
Section titled “Reading middleware data inside the route”The route begins:
async def product_page(request: Request, product_id: int):The route and middleware work with the same incoming request context. Starlette may wrap that context in different Python Request objects; the useful guarantee here is that they share the request’s state.
That means the value stored earlier still exists:
request_id = request.state.request_idThe data traveled through the application like this:
Middleware creates request ID ↓Middleware stores it on request.state ↓Middleware passes the request through call_next ↓Router passes that Request object to the route ↓Route reads request.state.request_idThe route does not generate another ID. It retrieves the one already associated with the request.
This is a basic example of passing request-specific context from an outer layer to an inner layer.
The route returns HTML
Section titled “The route returns HTML”The route returns:
return f"""<html> <body> <h1>Product {product_id}</h1> <p>Request ID: {request_id}</p> </body></html>"""Python replaces the f-string expressions with their current values.
The resulting text resembles:
<html> <body> <h1>Product 42</h1> <p> Request ID: 8f37f744-0c15-4edf-a773-b123d56659ef </p> </body></html>Because the route specifies:
response_class=HTMLResponseFastAPI packages this string into an HTMLResponse object.
That object contains:
- A status code
- Headers
- An HTML response body
At this point, the response exists, but it has not reached the browser.
It must travel back through the middleware.
Returning from call_next
Section titled “Returning from call_next”The route has finished, and call_next(request) now produces the response:
response = await call_next(request)Execution resumes on the next line:
elapsed_ms = (time.perf_counter() - start_time) * 1000Python takes a second timer reading:
time.perf_counter()It subtracts the reading captured before call_next:
time.perf_counter() - start_timeThe result is measured in seconds.
If the result were:
0.00184that would mean 0.00184 seconds.
Multiplying by 1,000 converts seconds into milliseconds:
0.00184 * 1000The measured time includes the downstream work performed inside call_next.
In a larger application, that could include:
- Router matching
- Authentication dependencies
- Pydantic validation
- Service functions
- SQLAlchemy queries
- Jinja rendering
- Response creation
It does not normally represent the complete time perceived by the user. Browser rendering, internet latency, proxies, and other network activity exist outside this particular measurement.
It measures the server-side section wrapped by the middleware.
For a streaming response, call_next() can return once the response begins, while its body continues afterward. Our timer therefore does not measure the complete delivery of a long stream. Likewise, an unhandled exception can leave call_next() by raising, so the lines that add these headers do not automatically run for every possible server failure.
Modifying the outgoing response
Section titled “Modifying the outgoing response”Now the middleware adds two headers:
response.headers["X-Request-ID"] = request_idThis places the request identifier in the HTTP response.
The browser or another API client can now see which request produced that response.
Next:
response.headers["X-Process-Time-Ms"] = f"{elapsed_ms:.2f}"The formatting expression:
f"{elapsed_ms:.2f}"converts the number into a string with two decimal places.
For example:
1.837492becomes:
"1.84"HTTP header values are text, so converting the number to a string is necessary.
The response may now resemble:
HTTP/1.1 200 OKContent-Type: text/html; charset=utf-8X-Request-ID: 8f37f744-0c15-4edf-a773-b123d56659efX-Process-Time-Ms: 1.84Notice that the route did not add these headers.
This is exactly why middleware is useful: cross-cutting behavior can be implemented once instead of repeated in every route.
Without middleware, you might need to write request-timing code inside:
product_page()user_page()dashboard_page()login()create_order()That would mix application-wide infrastructure concerns into business-specific route functions.
Returning the response
Section titled “Returning the response”The final line is:
return responseThis hands the modified response back to the server.
The server serializes the HTTP response and sends it across the connection to the browser.
The browser then:
- Reads the
200 OKstatus. - Reads the response headers.
- Recognizes
Content-Type: text/html. - Parses the HTML body.
- Renders the product page.
The custom timing and request-ID headers do not automatically appear visibly on the page.
They are metadata, not HTML.
You could inspect them in the browser’s developer tools under the Network panel.
The request ID appears in the page only because our route deliberately inserted it into the HTML:
<p>Request ID: {request_id}</p>The complete execution order
Section titled “The complete execution order”For this request:
GET /products/42the execution sequence is:
- The browser creates an HTTP request.
- The server receives it.
- FastAPI creates or exposes a
Requestobject. add_request_context()begins.- The middleware generates a request ID.
- The middleware stores it on
request.state. - The middleware records the starting timer value.
- The middleware calls
await call_next(request). - FastAPI’s router matches
GET /products/{product_id}. - FastAPI converts
"42"into the integer42. - FastAPI supplies the current
Requestobject. product_page()runs.- The route reads the request ID from
request.state. - The route returns an HTML string.
- FastAPI creates an
HTMLResponse. call_next()returns that response to the middleware.- The middleware calculates elapsed time.
- The middleware adds two response headers.
- The middleware returns the response.
- The server sends it to the browser.
- The browser renders the HTML.
The request travels inward:
Browser → server → middleware → router → routeThe response travels outward:
Route → middleware → server → browserWhy middleware is powerful
Section titled “Why middleware is powerful”Middleware is appropriate for behavior that applies broadly across the application.
Typical examples include:
- Request logging
- Request IDs
- Performance timing
- Trusted-host enforcement
- Session-cookie handling
- CORS headers
- Response compression
- Security headers
The shared characteristic is scope.
These concerns apply to many or all requests, regardless of which business route eventually handles them.
What middleware should usually not contain
Section titled “What middleware should usually not contain”Middleware is usually the wrong place for route-specific business logic.
For example:
if request.url.path == "/products/42": update_product_inventory()That technically could be written, but it would hide product behavior inside an application-wide infrastructure layer.
Product logic belongs in the route, dependency, or service layer where it can be understood and tested in context.
A practical separation is:
- Middleware: concerns that wrap the application
- Dependencies: reusable requirements needed by selected routes
- Routes: HTTP-specific orchestration
- Services: business operations
- Models and repositories: persistence and database behavior
We’ll build those distinctions gradually.
Middleware can stop the request
Section titled “Middleware can stop the request”Our middleware always calls:
await call_next(request)But middleware is not required to do so.
It could return a response immediately:
@app.middleware("http")async def maintenance_mode(request: Request, call_next): if maintenance_is_enabled: return HTMLResponse( "Temporarily unavailable", status_code=503, )
return await call_next(request)When maintenance mode is enabled, call_next() never runs.
That means:
- The router never selects a route.
- Dependencies do not execute.
- The route function does not execute.
- The middleware itself generates the response.
This is called short-circuiting the request pipeline.
It is powerful, but broad. Because middleware affects the whole application, it must be used carefully.
Authentication is a good example of that tradeoff. Global middleware can sometimes identify a user, but route dependencies are often better for enforcing which particular routes require authentication or permissions.
Multiple middleware form a stack
Section titled “Multiple middleware form a stack”If an application has multiple middleware layers, they wrap each other.
Suppose we have:
TrustedHost middlewareRequest context middlewareSession middlewareRouterThe incoming request might travel:
TrustedHost → Request context → Session → RouterThe response reverses direction:
Router → Session → Request context → TrustedHostThis is often called the onion model because each middleware forms another layer around the application.
FastAPI’s documented rule is that the outer middleware runs first for the incoming request and last for the outgoing response. (FastAPI middleware execution order)
The reversal is not arbitrary. It follows naturally from nested function calls.
If function A calls function B, and B calls function C:
A begins B begins C runs B finishesA finishesMiddleware behaves the same way.
The central idea
Section titled “The central idea”Middleware does not replace routing.
It surrounds routing.
The crucial line:
response = await call_next(request)means:
Pause this middleware’s incoming work, let the rest of the application process the request, and then give this middleware the resulting response.
Everything before that line happens while the request travels inward.
Everything after it happens while the response travels outward.
That one mental model explains most ordinary FastAPI middleware:
@app.middleware("http")async def middleware(request, call_next): # Incoming side
response = await call_next(request)
# Outgoing side
return responseThe next layer to add is authentication: how an application uses information such as a session cookie or authorization header to determine who made the request, before authorization decides what that person is allowed to do.