Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 50 ยท Structuring larger apps

Middleware and CORS

Write FastAPI HTTP middleware for timing and request IDs, configure CORSMiddleware for browser apps, add GZip and trusted hosts, and learn the middleware order.

Dependencies run around one endpoint. Sometimes you need code that wraps every request, including requests that match no route and responses that FastAPI generates itself: measuring how long a request took, attaching an id to the response, compressing the body, or telling browsers which websites may call your API. That is the job of middleware.

A middleware is a function (or class) that sits between the server and your application. It receives each request, may change it, passes it inward, then receives the response on the way out and may change that too. In this lesson you will write your own middleware, use the ready-made ones for CORS, compression and host checking, and learn why the order of middleware matters.

How middleware wraps your app

Picture an onion. The request enters through the outer layer, travels inward layer by layer to the endpoint, and the response travels back out through the same layers in reverse.

flowchart LR
    C["Client"] --> M1["Middleware A (outer)"]
    M1 --> M2["Middleware B (inner)"]
    M2 --> E["Router and endpoint"]
    E --> M2
    M2 --> M1
    M1 --> C

Requests travel inward through each layer; responses travel back out through the same layers.

Use middleware for behavior that applies to the whole app and does not care which endpoint was chosen. Use a dependency when the behavior belongs to particular routes or needs values passed to the endpoint.

Writing HTTP middleware

The decorator @app.middleware("http") turns an async function into middleware. It receives the request and a function call_next. Awaiting call_next(request) passes the request inward and gives you back the response, so everything before the await happens on the way in, and everything after it on the way out.

The next example registers two middleware and logs when each one starts and finishes. Run it and read the order carefully, because it is not what most people guess.

Python Middleware order: the last one added runs first

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The log reads second_added: in, first_added: in, endpoint, first_added: out, second_added: out. The middleware added last is the outermost layer, so it sees the request first and the response last. Each add_middleware call (and each @app.middleware) wraps everything added before it. The header X-First made it into the response because first_added modified the response object on the way out.

A practical middleware: request ID and timing

Two very common jobs: give each request an id so log lines for one request can be connected, and measure how long it took. The middleware below reuses an X-Request-ID sent by the caller (for example a proxy) or makes one up, stores it on request.state so endpoints can read it, and puts it on the response together with the elapsed time.

Python Request id and timing middleware

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first request keeps the caller's id and the endpoint sees the same one. The second gets a generated id (req- plus 8 characters, 12 in total). The third shows the key advantage over a dependency: even a 404 for a URL with no route carries the X-Request-ID header, because the middleware wraps routing itself.

@app.middleware("http") is built on Starlette's BaseHTTPMiddleware, which is convenient and fine for most apps. It has known limitations: it reads responses as streams and adds some overhead, so for very high-traffic apps or special cases (streaming, background tasks, WebSockets) people write pure ASGI middleware instead. Start simple and optimize only when you have a reason.

CORS: letting browsers call your API

Browsers enforce the same-origin policy: JavaScript running on https://app.example.com may not read responses from a different origin such as https://api.example.com unless the API explicitly allows it. The permission mechanism is called CORS (Cross-Origin Resource Sharing). An origin is the combination of scheme, host and port, so http://localhost:3000 and http://localhost:8000 are different origins.

CORS is enforced by the browser, not the server. The server only sends headers; a browser that sees no permission refuses to give the response to the page's JavaScript. Tools like curl ignore CORS completely, which is why CORS is not a security feature against attackers calling your API directly.

For "non-simple" requests (a DELETE, or a POST with a JSON body and an Authorization header), the browser first sends a preflight: an OPTIONS request asking "would you accept this method and these headers from this origin?". The CORSMiddleware answers preflights for you.

Python CORSMiddleware: simple requests and preflight

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

What the output tells you:

  • No Origin header (a same-origin page or a non-browser client): no CORS headers are added.
  • Allowed origin: the response echoes it in access-control-allow-origin, so the browser lets the page read the data.
  • Other origin: the request still succeeds with 200, but there is no access-control-allow-origin header, so the browser hides the response from that page's JavaScript.
  • Preflight for POST with an Authorization header: answered with 200 and the allowed methods, headers and max-age (how long the browser may cache the answer).
  • Preflight for DELETE, which we did not allow: 400 Disallowed CORS method.

CORS rules of thumb

  • List your real front-end origins in allow_origins. Using ["*"] is fine for fully public APIs without cookies or credentials, and nothing else.
  • allow_credentials=True (cookies, HTTP auth) cannot be combined with a wildcard origin in browsers, so list origins explicitly.
  • Origins must match exactly, including https versus http, the port, and no trailing slash.
  • During development, a common mistake is allowing localhost:3000 but calling from 127.0.0.1:3000: a different origin.

GZip and trusted hosts

Two more built-in middleware solve everyday problems. GZipMiddleware compresses responses larger than minimum_size bytes for clients that send Accept-Encoding: gzip, which saves bandwidth for large JSON lists. TrustedHostMiddleware rejects requests whose Host header is not on your list, which defends against host-header attacks (for example, forged password-reset links built from the Host value).

Python GZipMiddleware and TrustedHostMiddleware

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The big response was compressed (gzip): len(r.content) is 2910 bytes after the client unpacked it, while the content-length header says only 83 bytes crossed the wire. The tiny response stayed below minimum_size, and a client that asked for identity got the plain body. The request to evil.test was answered with 400 Invalid host header.

HTTPSRedirectMiddleware

HTTPSRedirectMiddleware answers every plain http:// or ws:// request with a redirect to the https:// / wss:// version of the same URL. It is the last of Starlette's built-in security middleware, and it is two lines to use:

Python
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware

app.add_middleware(HTTPSRedirectMiddleware)

It decides by looking at the scheme the app sees. The redirect is a 307, so the method is preserved, and the middleware does not redirect requests that already arrived over HTTPS.

Python HTTPSRedirectMiddleware in action

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The plain-HTTP request got 307 Temporary Redirect to the HTTPS URL (the query string is kept), while the HTTPS request went straight through.

Behind a reverse proxy that terminates TLS, your app only ever sees plain HTTP from the proxy. Adding HTTPSRedirectMiddleware there causes an endless redirect loop unless uvicorn trusts the proxy's X-Forwarded-Proto header (--proxy-headers with --forwarded-allow-ips, as described in Deployment). Most teams do the redirect in the proxy or load balancer instead, and skip the middleware.

HTTPS redirects pair well with an HSTS header (Strict-Transport-Security), which tells browsers to use HTTPS for a given period without asking first. Add it in the proxy, or with a small @app.middleware("http") function.

Uvicorn options worth knowing

Middleware lives in your code. Many related behaviours are configured on the server that runs your app, with uvicorn's command-line flags (the same names exist as arguments to uvicorn.run). These are the ones you will use most:

Option What it does
--host 0.0.0.0 / --port 8000 Where to listen (127.0.0.1 is the default, reachable only from the same machine)
--reload Restart when files change; development only, never in production
--reload-dir app Watch only the given folders
--workers 4 Number of worker processes (cannot be combined with --reload)
--log-level debug / info / warning How much uvicorn logs
--no-access-log Silence the per-request access log
--proxy-headers, --forwarded-allow-ips Trust X-Forwarded-For/Proto from the listed proxies
--root-path /api The public prefix removed by a proxy (see Mounting sub-applications)
--ssl-keyfile key.pem --ssl-certfile cert.pem Serve HTTPS directly (handy for local testing; in production a proxy usually does TLS)
--timeout-keep-alive 5 Seconds to keep idle connections open
--limit-concurrency N Refuse (503) beyond N concurrent connections
--env-file .env Load environment variables from a file
--lifespan on Force lifespan handling on or off (auto by default)

For example, a local HTTPS run with a self-signed certificate (read-only, needs OpenSSL):

Terminal
openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 30 -subj "/CN=localhost"
uvicorn app.main:app --reload --ssl-keyfile key.pem --ssl-certfile cert.pem --log-level debug

With the fastapi CLI (fastapi dev, fastapi run) many of the same options exist under similar names; run fastapi run --help to see them.

Middleware order matters

Because the last-added middleware is outermost, add them in the order that makes sense from the outside in and remember it reads backwards in the code. Some consequences:

  • Put CORSMiddleware on the outside so even error responses (and the 400 of other middleware) still carry CORS headers; otherwise the browser reports a confusing CORS error instead of your real error.
  • TrustedHostMiddleware is usually near the outside so bad hosts are rejected before any work happens.
  • A timing middleware measures everything inside it. Add it last if you want to include the other middleware's time, first if you want only the app itself.
  • GZipMiddleware should be inside any middleware that needs to read response bodies, because it changes them.

In a real project main.py is where you add them all in one place, as described in Routers and project layout. Request ids and CORS settings usually come from settings, and request-id middleware is a core ingredient of the production service project.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You add middleware A and then middleware B with add_middleware. Which sees an incoming request first?

    Each added middleware wraps the ones before it, so the last added is outermost: it runs first on the way in and last on the way out.
  2. 2. A page on https://app.example.com calls your API, which allows only https://admin.example.com. What happens?

    The server may still process the request. The browser enforces CORS by withholding the response from scripts of a non-allowed origin.
  3. 3. Which statement about CORS is true?

    CORS only controls what browser scripts may read. Anyone can call your API directly, so you still need authentication and authorization.
  4. 4. What does GZipMiddleware(minimum_size=500) do with a 200-byte response?

    Compressing tiny bodies costs CPU and may even make them larger, so responses below the minimum size are sent as they are.
  5. 5. Why does a request-id middleware add its header even to a 404 for an unknown URL?

    Middleware sits outside the router, so it sees every request and every response, including the ones FastAPI generates for unknown paths.

Summary

  • Middleware wraps every request: code before await call_next(request) runs on the way in, code after it on the way out.
  • The middleware added last is the outermost; think from the outside in when ordering them.
  • Request ids, timing and logging are classic middleware; request.state carries data to endpoints.
  • CORSMiddleware answers preflights and adds access-control-* headers; list exact origins, and remember CORS is a browser rule, not protection.
  • GZipMiddleware compresses large responses; TrustedHostMiddleware rejects unexpected Host headers.
  • Use dependencies for per-route behavior and middleware for app-wide behavior.

Next: Lifespan events and app state shows how to create shared resources once at startup and clean them up at shutdown.