You can define Header parameters the same way you define QueryPath and Cookie parameters.

Import Header

Python 3.6 full codes

 

from typing import Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: Union[str, None] = Header(default=None)):
    return {"User-Agent": user_agent}

First import Header:

=== "Python 3.6 and above"

from fastapi import FastAPI, Header

=== "Python 3.10 and above"

from fastapi import FastAPI, Header

Declare Header parameters

Then declare the header parameters using the same structure as with PathQuery and Cookie.

The first value is the default value, you can pass all the extra validation or annotation parameters:

=== "Python 3.6 and above"

async def read_items(user_agent: Union[str, None] = Header(default=None)):

=== "Python 3.10 and above"

async def read_items(user_agent: str | None = Header(default=None)):

!!! note "Technical Details" Header is a "sister" class of PathQuery and Cookie. It also inherits from the same common Param class.

But remember that when you import `Query`, `Path`, `Header`, and others from `fastapi`, those are actually functions that return special classes.

!!! info To declare headers, you need to use Header, because otherwise the parameters would be interpreted as query parameters.

Automatic conversion

Python 3.6 full codes

from typing import Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(
    strange_header: Union[str, None] = Header(default=None, convert_underscores=False)
):
    return {"strange_header": strange_header}

Header has a little extra functionality on top of what PathQuery and Cookie provide.

Most of the standard headers are separated by a "hyphen" character, also known as the "minus symbol" (-).

But a variable like user-agent is invalid in Python.

So, by default, Header will convert the parameter names characters from underscore (_) to hyphen (-) to extract and document the headers.

Also, HTTP headers are case-insensitive, so, you can declare them with standard Python style (also known as "snake_case").

So, you can use user_agent as you normally would in Python code, instead of needing to capitalize the first letters as User_Agent or something similar.

If for some reason you need to disable automatic conversion of underscores to hyphens, set the parameter convert_underscores of Header to False:

=== "Python 3.6 and above"

strange_header: Union[str, None] = Header(default=None, convert_underscores=False)

=== "Python 3.10 and above"

strange_header: str | None = Header(default=None, convert_underscores=False)

!!! warning Before setting convert_underscores to False, bear in mind that some HTTP proxies and servers disallow the usage of headers with underscores.

Duplicate headers

Python 3.6 full codes

from typing import List, Union

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(x_token: Union[List[str], None] = Header(default=None)):
    return {"X-Token values": x_token}

It is possible to receive duplicate headers. That means, the same header with multiple values.

You can define those cases using a list in the type declaration.

You will receive all the values from the duplicate header as a Python list.

For example, to declare a header of X-Token that can appear more than once, you can write:

=== "Python 3.6 and above"

async def read_items(x_token: Union[List[str], None] = Header(default=None)):

=== "Python 3.9 and above"

async def read_items(x_token: Union[list[str], None] = Header(default=None)):

=== "Python 3.10 and above"

async def read_items(x_token: list[str] | None = Header(default=None)):

If you communicate with that path operation sending two HTTP headers like:

X-Token: foo
X-Token: bar

The response would be like:

{
    "X-Token values": [
        "bar",
        "foo"
    ]
}

keywords: pythonFastAPI