Skip to content

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.

We’ll expand the product page from the first tutorial:

import time
from uuid import uuid4
from fastapi import FastAPI, Request
from 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/42

it 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-b123d56659ef
X-Process-Time-Ms: 1.84

Your actual values would be different.


As before, we must distinguish:

  1. Application startup
  2. 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.

import time
from uuid import uuid4

These 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, Request
from fastapi.responses import HTMLResponse

FastAPI creates the application.

Request represents an incoming HTTP request.

HTMLResponse tells FastAPI that the route returns HTML rather than ordinary JSON data.

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.


@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_context

as part of the request-processing pipeline.

The middleware will therefore run for requests such as:

GET /products/42

It will also run for:

GET /docs

and:

POST /login

and even for a path that does not exist:

GET /something-that-is-not-here

This 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)


async def add_request_context(request: Request, call_next):

FastAPI provides this function with two arguments:

  • request
  • call_next

These are very different objects.

request: Request

request represents the incoming HTTP request.

It contains information such as:

request.method
request.url
request.headers
request.cookies
request.client
request.state

For our example request:

http://127.0.0.1:8000/products/42

some 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.

call_next

call_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.


Everything above this line runs on the incoming side:

response = await call_next(request)

Our first incoming operation is:

request_id = str(uuid4())

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 started
Database query started
Request started
Database query failed
Request completed

Which database query belongs to which request?

If each log entry includes a request ID, the sequence becomes traceable:

request=abc123 Request started
request=abc123 Database query started
request=xyz789 Request started
request=abc123 Database query failed
request=xyz789 Request completed

Request IDs help connect activity across middleware, routes, services, database operations, and logs.

This becomes especially valuable in production.


request.state.request_id = request_id

This 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_id

and assign our UUID string to it.

Afterward:

request.state.request_id

returns 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.


start_time = time.perf_counter()

time.perf_counter() returns a high-resolution timer value.

The number itself is not a normal clock time:

482150.183726

It 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.


response = await call_next(request)

This is the most important line in the middleware.

It divides the function into two sides:

# Incoming request side
request_id = str(uuid4())
request.state.request_id = request_id
start_time = time.perf_counter()
# Enter the rest of the application
response = await call_next(request)
# Outgoing response side
elapsed_ms = ...
response.headers[...] = ...
return response

You can picture the middleware as a wrapper:

Middleware begins
Application runs
Middleware finishes

Or, more specifically:

add_request_context begins
router selects product_page
product_page runs
product_page returns HTML
FastAPI builds an HTMLResponse
add_request_context receives that response
add_request_context modifies the response
add_request_context returns the response

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.


The request passed inward is still:

GET /products/42

FastAPI’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: int

FastAPI converts the text into the Python integer:

42

The route also declares:

request: Request

FastAPI recognizes the type and supplies the current Request object.

FastAPI therefore makes the conceptual call:

await product_page(
request=current_request,
product_id=42,
)

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_id

The 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_id

The 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:

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=HTMLResponse

FastAPI 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.


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) * 1000

Python takes a second timer reading:

time.perf_counter()

It subtracts the reading captured before call_next:

time.perf_counter() - start_time

The result is measured in seconds.

If the result were:

0.00184

that would mean 0.00184 seconds.

Multiplying by 1,000 converts seconds into milliseconds:

1.84
0.00184 * 1000

The 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.


Now the middleware adds two headers:

response.headers["X-Request-ID"] = request_id

This 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.837492

becomes:

"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 OK
Content-Type: text/html; charset=utf-8
X-Request-ID: 8f37f744-0c15-4edf-a773-b123d56659ef
X-Process-Time-Ms: 1.84

Notice 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.


The final line is:

return response

This 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:

  1. Reads the 200 OK status.
  2. Reads the response headers.
  3. Recognizes Content-Type: text/html.
  4. Parses the HTML body.
  5. 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>

For this request:

GET /products/42

the execution sequence is:

  1. The browser creates an HTTP request.
  2. The server receives it.
  3. FastAPI creates or exposes a Request object.
  4. add_request_context() begins.
  5. The middleware generates a request ID.
  6. The middleware stores it on request.state.
  7. The middleware records the starting timer value.
  8. The middleware calls await call_next(request).
  9. FastAPI’s router matches GET /products/{product_id}.
  10. FastAPI converts "42" into the integer 42.
  11. FastAPI supplies the current Request object.
  12. product_page() runs.
  13. The route reads the request ID from request.state.
  14. The route returns an HTML string.
  15. FastAPI creates an HTMLResponse.
  16. call_next() returns that response to the middleware.
  17. The middleware calculates elapsed time.
  18. The middleware adds two response headers.
  19. The middleware returns the response.
  20. The server sends it to the browser.
  21. The browser renders the HTML.

The request travels inward:

Browser
→ server
→ middleware
→ router
→ route

The response travels outward:

Route
→ middleware
→ server
→ browser

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.


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.


If an application has multiple middleware layers, they wrap each other.

Suppose we have:

TrustedHost middleware
Request context middleware
Session middleware
Router

The incoming request might travel:

TrustedHost
→ Request context
→ Session
→ Router

The response reverses direction:

Router
→ Session
→ Request context
→ TrustedHost

This 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 finishes
A finishes

Middleware behaves the same way.


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 response

The 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.