tiangolo.fastapi/docs/en/docs/tutorial/middleware.md

Middleware

You can add middleware to FastAPI applications.

In this tutorial we will discuss how to add a custom http middleware to your FastAPI applications.

The http middleware is designed to work with HTTP protocol, and it is responsible for handling of HTTP requests and responses.

How http middleware works?

The http middleware works with every request before it is processed by any specific path operation. And also with every response before returning it.

• It takes each request that comes to your application.
• It can then do something to that request or run any needed code.
• Then it passes the request to be processed by the rest of the application (by some path operation).
• It then takes the response generated by the application (by some path operation).
• It can do something to that response or run any needed code.
• Then it returns the response.

/// note | Technical Details

If you have dependencies with yield, the exit code will run after the middleware.

If there were any background tasks (covered in the Background Tasks{.internal-link target=_blank} section, you will see it later), they will run after all the middleware.

///

Create a middleware

To create a middleware you use the decorator @app.middleware("http") on top of a function.

The middleware function receives:

• The request.
• A function call_next that will receive the request as a parameter.
  • This function will pass the request to the corresponding path operation.
  • Then it returns the response generated by the corresponding path operation.
• You can then further modify the response before returning it.

{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}

/// tip

Keep in mind that custom proprietary headers can be added using the 'X-' prefix.

But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your CORS configurations (CORS (Cross-Origin Resource Sharing){.internal-link target=_blank}) using the parameter expose_headers documented in Starlette's CORS docs.

///

/// note | Technical Details

You could also use from starlette.requests import Request.

FastAPI provides it as a convenience for you, the developer. But it comes directly from Starlette.

///

Before and after the response

You can add code to be run with the request, before any path operation receives it.

And also after the response is generated, before returning it.

For example, you could add a custom header X-Process-Time containing the time in seconds that it took to process the request and generate a response:

{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}

/// tip

Here we use time.perf_counter() instead of time.time() because it can be more precise for these use cases. 🤓

///

/// note | Technical Details

As you noticed the decorator @app.middleware('http') contains a parameter called http. This parameter defines the type of server events to be handled by the middleware, and hence the name http middleware.

ASGI server supports the following scope types (or event types): lifespan, http, and websocket.

///

Class-Based Middleware

It is possible to define a custom http middleware using classes.

We will implement a class-based middleware with exactly the same functionality as in the example with the @app.middleware('http') decorator.

We will use an abstract BaseHTTPMiddleware class from Starlette that allows to write custom http middlewares.

{* ../../docs_src/middleware/tutorial002.py hl[7:13,17] *}

To create the middleware we need to override the async dispatch method of the BaseHTTPMiddleware class.

The functionality of the method is very similar to the decorated middleware function from the previous example.

The middleware is connected to the FastAPI application using app.add_middleware method.

/// note

You can read more about Starlette middleware in Starlette documentation.

///

Other middlewares

You can later read more about other middlewares in the Advanced User Guide: Advanced Middleware{.internal-link target=_blank}.

You will read about how to handle CORS with a middleware in the next section.