Modelos de Parâmetros do Cabeçalho¶

Se você possui um grupo de parâmetros de cabeçalho relacionados, você pode criar um modelo do Pydantic para declará-los.

Isso vai lhe permitir reusar o modelo em múltiplos lugares e também declarar validações e metadados para todos os parâmetros de uma vez. 😎

Parâmetros do Cabeçalho com um Modelo Pydantic¶

Declare os parâmetros de cabeçalho que você precisa em um modelo do Pydantic, e então declare o parâmetro como Header:

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
    return headers

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
    return headers

O FastAPI irá extrair os dados de cada campo a partir dos cabeçalhos da requisição e te retornará o modelo do Pydantic que você definiu.

Confira a documentação¶

Você pode ver os headers necessários na interface gráfica da documentação em /docs:

Proíba Cabeçalhos adicionais¶

Em alguns casos de uso especiais (provavelmente não muito comuns), você pode querer restringir os cabeçalhos que você quer receber.

Você pode usar a configuração dos modelos do Pydantic para proibir quaisquer campos extra com forbid:

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    model_config = {"extra": "forbid"}

    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
    return headers

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    model_config = {"extra": "forbid"}

    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
    return headers

Se um cliente tentar enviar alguns cabeçalhos extra, eles irão receber uma resposta de erro.

Por exemplo, se o cliente tentar enviar um cabeçalho tool com o valor plumbus, ele irá receber uma resposta de erro informando que o parâmetro do cabeçalho tool não é permitido:

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["header", "tool"],
            "msg": "Extra inputs are not permitted",
            "input": "plumbus",
        }
    ]
}

Desative a conversão de underscores¶

Da mesma forma que com parâmetros de cabeçalho normais, quando você tem caracteres de sublinhado nos nomes dos parâmetros, eles são automaticamente convertidos em hifens.

Por exemplo, se você tem um parâmetro de cabeçalho save_data no código, o cabeçalho HTTP esperado será save-data, e ele aparecerá assim na documentação.

Se por algum motivo você precisar desativar essa conversão automática, também poderá fazê-lo para modelos do Pydantic para parâmetros de cabeçalho.

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(
    headers: Annotated[CommonHeaders, Header(convert_underscores=False)],
):
    return headers

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/items/")
async def read_items(headers: CommonHeaders = Header(convert_underscores=False)):
    return headers

Combine Modelos de Parâmetros¶

Você pode combinar múltiplos modelos de parâmetros de cabeçalho com parâmetros de cabeçalho individuais e dependências. Cada modelo é extraído e validado de forma independente, conforme explicado para modelos de parâmetros de consulta.

A configuração extra de cada modelo se aplica a todos os parâmetros de cabeçalho, incluindo aqueles declarados em outros modelos ou dependências. Com extra="forbid", qualquer cabeçalho fora desse modelo é rejeitado. Com extra="allow", esses cabeçalhos são incluídos como campos extras do modelo.

Cada modelo usa sua própria configuração Header(convert_underscores=...), tanto ao ler a requisição quanto ao gerar o OpenAPI. Aliases explícitos de campos permanecem como nomes literais de cabeçalhos.

Modelos Opcionais de Parâmetros de Cabeçalho¶

Declare um modelo de parâmetros de cabeçalho com | None e um valor padrão de None para tornar o grupo opcional.

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class ClientHeaders(BaseModel):
    x_client_name: str
    x_client_version: str


@app.get("/items/")
async def read_items(client: Annotated[ClientHeaders | None, Header()] = None):
    return client

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()


class ClientHeaders(BaseModel):
    x_client_name: str
    x_client_version: str


@app.get("/items/")
async def read_items(client: ClientHeaders | None = Header(default=None)):
    return client

Se nem x-client-name nem x-client-version forem enviados, client será None. Se qualquer um deles for enviado, o FastAPI validará o modelo e exigirá ambos os campos.

As mesmas regras para valores padrão, campos extras e OpenAPI se aplicam aos modelos opcionais de parâmetros de consulta.

Cabeçalhos como Host também seguem a configuração extra do modelo. Com extra="allow", eles tornam o modelo presente mesmo que nenhum dos campos declarados seja fornecido.

Resumo¶

Você pode utilizar modelos do Pydantic para declarar cabeçalhos no FastAPI. 😎