YouTipFastapi Header Cookie
FastAPI provides the `Header` and `Cookie` types for retrieving data from HTTP request headers and Cookies.
* * *
## Header Parameters
Use `Header` to declare header parameters:
## Instance
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
# Receive User-Agent header
user_agent: Annotated[str | None, Header()]=None,
):
return{"User-Agent": user_agent}
Access **http://127.0.0.1:8000/items/**, and the returned JSON will contain the browser's User-Agent information.
* * *
## Automatic Conversion of Headers
Field names in HTTP headers use hyphens (e.g., `X-Token`), while Python variable names cannot contain hyphens. FastAPI will automatically perform the conversion:
## Instance
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
# Python variable name uses underscores, FastAPI automatically converts to X-Token header
x_token: Annotated[list | None, Header()]=None,
):
return{"X-Token values": x_token}
Conversion rules:
| Python Variable Name | HTTP Header | Description |
| --- | --- | --- |
| `x_token` | `X-Token` | Underscores are automatically converted to hyphens |
| `user_agent` | `User-Agent` | Same as above |
| `content_type` | `Content-Type` | Same as above |
> FastAPI automatically converts underscores `_` in variable names to hyphens `-` to match headers. If you need to disable this conversion, set `Header(convert_underscores=False)`.
* * *
## Receiving Duplicate Headers
Some headers may appear multiple times (e.g., `Set-Cookie`), use the `list` type to receive them:
## Instance
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
# Receive multiple X-Token headers
x_token: Annotated[list | None, Header()]=None,
):
return{"X-Token values": x_token}
Request example:
GET /items/ HTTP/1.1
X-Token: foo
X-Token: bar
Response: `{"X-Token values": ["foo", "bar"]}`
* * *
## Cookie Parameters
Use `Cookie` to declare Cookie parameters:
## Instance
from typing import Annotated
from fastapi import FastAPI,Cookie
app = FastAPI()
@app.get("/items/")
async def read_items(
# Receive Cookie named session_token
session_token: Annotated[str | None,Cookie()]=None,
):
return{"session_token": session_token}
* * *
## Using Headers and Cookies Together
You can retrieve both headers and Cookies in the same route:
## Instance
from typing import Annotated
from fastapi import FastAPI, Header,Cookie
app = FastAPI()
@app.get("/items/")
async def read_items(
user_agent: Annotated[str | None, Header()]=None,
session_token: Annotated[str | None,Cookie()]=None,
ads_id: Annotated[str | None,Cookie()]=None,
):
return{
"User-Agent": user_agent,
"Session-Token": session_token,
"Ads-ID": ads_id,
}
!(#)
* * *
## Summary
* Use `Header` to get HTTP header parameters
* Use `Cookie` to get Cookie parameters
* FastAPI automatically converts underscores in Python variable names to hyphens in headers
* Use `list` to receive duplicate headers
* Header and Cookie parameters support the same validation rules as query parameters