FastAPI Behind a Reverse Proxy: Fixing Docs URLs
A reverse proxy can hide the full URL from your FastAPI app, breaking OpenAPI docs. Tell your app about the proxy's path prefix by setting the root_path during initialization to ensure all generated URLs are correct.
Why it exists
To scale and secure applications, we place them behind reverse proxies like Nginx, Traefik, or cloud load balancers. These proxies handle SSL, load balancing, and routing, but they can alter the request path, making the app unaware of its public-facing URL.
The mental model
Your FastAPI application is like a tenant in a large office building. It knows its own internal layout perfectly (its routes like /users and /items). The reverse proxy is the building's main entrance and directory. A visitor asks the front desk for "Accounting, 12th floor" (/api/v1/users), and the front desk directs them to the correct office (/users). Your app needs to be told its full public address (/api/v1) to give correct directions back to visitors, like generating correct OpenAPI URLs.
How it works
When a proxy forwards a request, it might strip a prefix. For example, a public request to https://my-api.com/service/v1/users might arrive at your FastAPI server as just /users. FastAPI, by default, thinks its root is /. This causes its OpenAPI documentation (/docs) to generate incorrect server URLs and "Try it out" requests that fail because they call the wrong path. To fix this, you provide the root_path parameter when initializing your app: app = FastAPI(root_path="/service/v1"). This tells FastAPI to prepend this path to all generated URLs.
When to use it
Use root_path whenever your FastAPI application is deployed behind a reverse proxy that modifies the URL path. This is common in containerized environments like Docker with Traefik or Kubernetes with an Ingress controller. If your /docs UI loads but the "Try it out" button results in a 404 error, this is almost always the cause.
When not to use it
You don't need root_path if the proxy forwards the path unaltered or if you are running the app directly for local development without a proxy. Setting it incorrectly will cause your app to generate wrong URLs. If the proxy only handles domain mapping (e.g., api.example.com to localhost:8000) without stripping any path, root_path is unnecessary.
One canonical example
A user navigates to https://my-api.com/api/v1/docs. The proxy strips /api/v1 and forwards the request for /docs to the FastAPI container. Without configuration, the OpenAPI UI loads, but when the user clicks "Try it out" for the /users endpoint, it makes a request to https://my-api.com/users (a 404), not https://my-api.com/api/v1/users. The fix is initializing the app with app = FastAPI(root_path="/api/v1"). Now, the OpenAPI spec correctly lists the server URL as https://my-api.com/api/v1, and all UI interactions work as expected.
Interview question
When deploying a FastAPI application behind a reverse proxy, what problem does configuring root_path primarily solve?
- a.To inform FastAPI about the public URL prefix that the proxy might remove, ensuring all generated URLs are accurate.Correct
- b.To optimize the reverse proxy's caching strategies for improved API performance.
- c.To enable the reverse proxy to handle SSL termination and secure client connections.
- d.To configure the reverse proxy's load balancing algorithm for distributing requests to FastAPI instances.
Why? this is the answer
FastAPI's root_path parameter is used to tell the application about the public-facing URL prefix that a reverse proxy might strip before forwarding requests. This ensures that FastAPI generates correct URLs for clients, particularly for OpenAPI documentation and 'Try it out' features. Other options describe functions of a reverse proxy itself, not what root_path configures within FastAPI.
Just read this? Test yourself on what you have been reading.
Read the original → fastapi.tiangolo.com
- #fastapi
- #python
- #reverse-proxy
- #networking
- #openapi
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on fastapi — each one lists the topics its interview covers.
See open roles