-
-```console
-$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
-
-INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
-```
-
-
+Open your browser and go to http://127.0.0.1:9999/api/v1/app
The response will look something like this:
```JSON
{
"message": "Hello World",
+ "path": "/api/v1/app",
"root_path": "/api/v1"
}
```
@@ -355,7 +478,7 @@ You should probably use it unless you have a specific reason to do otherwise.
Unfortunately, not all ASGI servers support a `--root-path` option or automatically adjust the `path` in the ASGI scope.
If your server doesn't, you can use one of the alternative approaches described below.
-#### Passing `root_path` as an argument to FastAPI (proxy keeps prefix)
+#### Passing `root_path` as an argument to FastAPI (proxy keeps prefix) { #passing-root-path-as-an-argument-to-fastapi-proxy-keeps-prefix }
If the proxy keeps the prefix in the forwarded request:
@@ -377,15 +500,30 @@ If the proxy keeps the prefix in the forwarded request:
url = "http://127.0.0.1:8000"
```
+(don't forget to restart Traefik to apply new config)
+
you can configure FastAPI like this:
{* ../../docs_src/behind_a_proxy/tutorial002.py hl[3] *}
+And run your ASGI server **without** `--root-path` option:
+
+
+
+```console
+$ fastapi run main.py --forwarded-allow-ips="*"
+
+INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+
+
In this setup:
-The app receives requests with `/api/v1` included in the path.
-
-FastAPI uses the `root_path` parameter to adjust the ASGI scope so that routing, redirects, and URL generation work correctly.
+* User requests `http://127.0.0.1:9999/api/v1/app`
+* The proxy sends `/api/v1/app` to the ASGI server (Uvicorn)
+* ASGI server passes `/api/v1/app` to your app
+* FastAPI uses the `root_path` parameter to adjust the ASGI scope so that routing, redirects, and URL generation work correctly.
Without the `root_path` parameter, the incoming scope from the ASGI server looks like this:
@@ -407,6 +545,18 @@ But thanks to the `root_path` parameter, FastAPI corrects the scope to:
}
```
+Open your browser and go to http://127.0.0.1:9999/api/v1/app
+
+The response will look something like this:
+
+```JSON
+{
+ "message": "Hello World",
+ "path": "/api/v1/app",
+ "root_path": "/api/v1"
+}
+```
+
/// warning | Attention
Don't forget - this setup assumes your app runs behind a proxy that **keeps (adds)** the `/api/v1` prefix when forwarding requests.
@@ -425,9 +575,9 @@ Otherwise, prefer using the `--root-path` approach [described above](#uvicorn-ro
///
-#### Using `X-Forwarded-Prefix` header
+#### Using `X-Forwarded-Prefix` header { #using-x-forwarded-prefix-header }
-This is another common approach. It's the most flexible, but requires a more initial configuration.
+This is another common approach. It's the most flexible, but requires more complex initial configuration.
/// warning
@@ -439,8 +589,9 @@ Imagine the prefix you use to serve the app might change over time. With the `--
Or, suppose you want to serve your app under multiple prefixes, such as `/api/v1` and `/backend/v1`. You would then need multiple instances of your app configured with different `--root-path` values - not ideal.
-There is a better solution for this! 💡
-Configure your reverse proxy to send the mount prefix in a header, e.g.:
+There is a better solution for this!
+
+💡 Configure your reverse proxy to send the mount prefix in a header, e.g.:
```
X-Forwarded-Prefix: /api/v1
@@ -488,11 +639,11 @@ Here is an example Traefik configuration:
You can then use middleware to read this header and dynamically set the correct `root_path`:
-{* ../../docs_src/behind_a_proxy/tutorial005.py *}
+{* ../../docs_src/behind_a_proxy/tutorial005.py hl[1:22] *}
This allows a single FastAPI instance to handle requests under multiple prefixes, with `root_path` correctly set for each request.
-Run the server:
+Run the server without `--root-path` option:
@@ -504,152 +655,40 @@ $ fastapi run main.py --forwarded-allow-ips="*"
-Test with `curl`:
+Open your browser and go to http://127.0.0.1:9999/api/v1/app
-```
-curl -H "x-forwarded-prefix: /api/v1" http://127.0.0.1:8000/api/v1/app
-# {"message":"Hello World","root_path":"/api/v1"}
-
-curl -H "x-forwarded-prefix: /backend/v1" http://127.0.0.1:8000/backend/v1/app
-# {"message":"Hello World","root_path":"/backend/v1"}
-```
-
-The same FastAPI instance now handles requests for multiple prefixes, using the correct `root_path` each time.
-
-## Testing locally with Traefik { #testing-locally-with-traefik }
-
-You can easily run the experiment locally with a stripped path prefix using Traefik.
-
-Download Traefik, it's a single binary, you can extract the compressed file and run it directly from the terminal.
-
-Then create a file `traefik.toml` with:
-
-```TOML hl_lines="3"
-[entryPoints]
- [entryPoints.http]
- address = ":9999"
-
-[providers]
- [providers.file]
- filename = "routes.toml"
-```
-
-This tells Traefik to listen on port 9999 and to use another file `routes.toml`.
-
-/// tip
-
-We are using port 9999 instead of the standard HTTP port 80 so that you don't have to run it with admin (`sudo`) privileges.
-
-///
-
-Now create that other file `routes.toml`:
-
-```TOML hl_lines="5 12 20"
-[http]
- [http.middlewares]
-
- [http.middlewares.api-stripprefix.stripPrefix]
- prefixes = ["/api/v1"]
-
- [http.routers]
-
- [http.routers.app-http]
- entryPoints = ["http"]
- service = "app"
- rule = "PathPrefix(`/api/v1`)"
- middlewares = ["api-stripprefix"]
-
- [http.services]
-
- [http.services.app]
- [http.services.app.loadBalancer]
- [[http.services.app.loadBalancer.servers]]
- url = "http://127.0.0.1:8000"
-```
-
-This file configures Traefik to use the path prefix `/api/v1`.
-
-And then Traefik will redirect its requests to your Uvicorn running on `http://127.0.0.1:8000`.
-
-Now start Traefik:
-
-
-
-```console
-$ ./traefik --configFile=traefik.toml
-
-INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
-```
-
-
-
-And now start your app, using the `--root-path` option:
-
-
-
-```console
-$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
-
-INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
-```
-
-
-
-### Check the responses { #check-the-responses }
-
-Now, if you go to the URL with the port for Uvicorn: http://127.0.0.1:8000/app, you will see the normal response:
-
-```JSON
+```json
{
"message": "Hello World",
+ "path": "/api/v1/app",
"root_path": "/api/v1"
}
```
-/// tip
+Now, go to http://127.0.0.1:9999/backend/v1/app
-Notice that even though you are accessing it at `http://127.0.0.1:8000/app` it shows the `root_path` of `/api/v1`, taken from the option `--root-path`.
-
-///
-
-And now open the URL with the port for Traefik, including the path prefix: http://127.0.0.1:9999/api/v1/app.
-
-We get the same response:
-
-```JSON
+```json
{
"message": "Hello World",
- "root_path": "/api/v1"
+ "path": "/backend/v1/app",
+ "root_path": "/backend/v1"
}
```
-but this time at the URL with the prefix path provided by the proxy: `/api/v1`.
+The same FastAPI instance now handles requests for multiple prefixes, using the correct `root_path` each time. 🎉
-Of course, the idea here is that everyone would access the app through the proxy, so the version with the path prefix `/api/v1` is the "correct" one.
+#### Important note { #important-note }
-And the version without the path prefix (`http://127.0.0.1:8000/app`), provided by Uvicorn directly, would be exclusively for the _proxy_ (Traefik) to access it.
+Of course, the idea here is that everyone would access the app through the proxy (`http://192.168.0.1:9999` in our configuration), and the the URLs requested by user would contain the path prefix `/api/v1`.
-That demonstrates how the Proxy (Traefik) uses the path prefix and how the server (Uvicorn) uses the `root_path` from the option `--root-path`.
+And URLs without the path prefix (`http://127.0.0.1:8000/app`), provided by Uvicorn directly, would be exclusively for the _proxy_ (Traefik) to access it.
-### Check the docs UI { #check-the-docs-ui }
+It's quite common mistake that people configure the ASGI server with `--root-path` option and then attempt to access it directly (without reverse proxy).
-But here's the fun part. ✨
+When `root_path` is configured (using any of the methods described above), always make sure that:
-The "official" way to access the app would be through the proxy with the path prefix that we defined. So, as we would expect, if you try the docs UI served by Uvicorn directly, without the path prefix in the URL, it won't work, because it expects to be accessed through the proxy.
-
-You can check it at http://127.0.0.1:8000/docs:
-
-
-
-But if we access the docs UI at the "official" URL using the proxy with port `9999`, at `/api/v1/docs`, it works correctly! 🎉
-
-You can check it at http://127.0.0.1:9999/api/v1/docs:
-
-
-
-Right as we wanted it. ✔️
-
-This is because FastAPI uses this `root_path` to create the default `server` in OpenAPI with the URL provided by `root_path`.
+* ✅ You are accessing your server via revers proxy
+* ✅ URL includes prefix
## Additional servers { #additional-servers }
diff --git a/docs/en/docs/img/tutorial/behind-a-proxy/image01.png b/docs/en/docs/img/tutorial/behind-a-proxy/image01.png
index 801203140..17216e302 100644
Binary files a/docs/en/docs/img/tutorial/behind-a-proxy/image01.png and b/docs/en/docs/img/tutorial/behind-a-proxy/image01.png differ
diff --git a/docs_src/behind_a_proxy/tutorial001.py b/docs_src/behind_a_proxy/tutorial001.py
index ede59ada1..406dc477f 100644
--- a/docs_src/behind_a_proxy/tutorial001.py
+++ b/docs_src/behind_a_proxy/tutorial001.py
@@ -5,4 +5,8 @@ app = FastAPI()
@app.get("/app")
def read_main(request: Request):
- return {"message": "Hello World", "root_path": request.scope.get("root_path")}
+ return {
+ "message": "Hello World",
+ "path": request.scope.get("path"),
+ "root_path": request.scope.get("root_path"),
+ }
diff --git a/docs_src/behind_a_proxy/tutorial002.py b/docs_src/behind_a_proxy/tutorial002.py
index c1600cde9..caaaf2dcb 100644
--- a/docs_src/behind_a_proxy/tutorial002.py
+++ b/docs_src/behind_a_proxy/tutorial002.py
@@ -5,4 +5,8 @@ app = FastAPI(root_path="/api/v1")
@app.get("/app")
def read_main(request: Request):
- return {"message": "Hello World", "root_path": request.scope.get("root_path")}
+ return {
+ "message": "Hello World",
+ "path": request.scope.get("path"),
+ "root_path": request.scope.get("root_path"),
+ }
diff --git a/docs_src/behind_a_proxy/tutorial005.py b/docs_src/behind_a_proxy/tutorial005.py
index 6548d4d7b..91f9e803f 100644
--- a/docs_src/behind_a_proxy/tutorial005.py
+++ b/docs_src/behind_a_proxy/tutorial005.py
@@ -24,4 +24,8 @@ app.add_middleware(ForwardedPrefixMiddleware)
@app.get("/app")
def read_main(request: Request):
- return {"message": "Hello World", "root_path": request.scope.get("root_path")}
+ return {
+ "message": "Hello World",
+ "path": request.scope.get("path"),
+ "root_path": request.scope.get("root_path"),
+ }
diff --git a/tests/test_tutorial/test_behind_a_proxy/test_tutorial001.py b/tests/test_tutorial/test_behind_a_proxy/test_tutorial001.py
index a070f850f..770caaa87 100644
--- a/tests/test_tutorial/test_behind_a_proxy/test_tutorial001.py
+++ b/tests/test_tutorial/test_behind_a_proxy/test_tutorial001.py
@@ -2,13 +2,17 @@ from fastapi.testclient import TestClient
from docs_src.behind_a_proxy.tutorial001 import app
-client = TestClient(app, root_path="/api/v1")
+client = TestClient(app, base_url="http://example.com/api/v1", root_path="/api/v1")
def test_main():
response = client.get("/app")
assert response.status_code == 200
- assert response.json() == {"message": "Hello World", "root_path": "/api/v1"}
+ assert response.json() == {
+ "message": "Hello World",
+ "path": "/api/v1/app",
+ "root_path": "/api/v1"
+ }
def test_openapi():
diff --git a/tests/test_tutorial/test_behind_a_proxy/test_tutorial002.py b/tests/test_tutorial/test_behind_a_proxy/test_tutorial002.py
index ce791e215..89742146b 100644
--- a/tests/test_tutorial/test_behind_a_proxy/test_tutorial002.py
+++ b/tests/test_tutorial/test_behind_a_proxy/test_tutorial002.py
@@ -6,9 +6,13 @@ client = TestClient(app)
def test_main():
- response = client.get("/app")
+ response = client.get("/api/v1/app")
assert response.status_code == 200
- assert response.json() == {"message": "Hello World", "root_path": "/api/v1"}
+ assert response.json() == {
+ "message": "Hello World",
+ "path": "/api/v1/app",
+ "root_path": "/api/v1",
+ }
def test_openapi():
diff --git a/tests/test_tutorial/test_behind_a_proxy/test_tutorial005.py b/tests/test_tutorial/test_behind_a_proxy/test_tutorial005.py
index 1bc8504d0..7240e9db8 100644
--- a/tests/test_tutorial/test_behind_a_proxy/test_tutorial005.py
+++ b/tests/test_tutorial/test_behind_a_proxy/test_tutorial005.py
@@ -26,17 +26,25 @@ def test_forwarded_prefix_middleware(
headers["x-forwarded-prefix"] = root_path
response = client.get(requested_path, headers=headers)
assert response.status_code == 200
+ assert response.json()["path"] == requested_path
assert response.json()["root_path"] == expected_root_path
-def test_openapi_servers():
+@pytest.mark.parametrize(
+ "prefix",
+ [
+ "/api/v1",
+ pytest.param("/backend/v1", marks=pytest.mark.xfail),
+ ],
+)
+def test_openapi_servers(prefix: str):
client = TestClient(app)
- headers = {"x-forwarded-prefix": "/api/v1"}
- response = client.get("/api/v1/openapi.json", headers=headers)
+ headers = {"x-forwarded-prefix": f"{prefix}"}
+ response = client.get(f"{prefix}/openapi.json", headers=headers)
assert response.status_code == 200
openapi_data = response.json()
assert "servers" in openapi_data
- assert openapi_data["servers"] == [{"url": "/api/v1"}]
+ assert openapi_data["servers"] == [{"url": prefix}]
@pytest.mark.parametrize(