Parámetros Header¶
Puedes definir parámetros Header de la misma manera que defines parámetros Query, Path y Cookie.
Importar Header¶
Primero importa Header:
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
return {"User-Agent": user_agent}
🤓 Otras versiones y variantes
Consejo
Preferible usar la versión con Annotated si es posible.
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: str | None = Header(default=None)):
return {"User-Agent": user_agent}
Declarar parámetros Header¶
Luego declara los parámetros header usando la misma estructura que con Path, Query y Cookie.
Puedes definir el valor por defecto así como todos los parámetros extra de validación o anotación:
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
return {"User-Agent": user_agent}
🤓 Otras versiones y variantes
Consejo
Preferible usar la versión con Annotated si es posible.
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: str | None = Header(default=None)):
return {"User-Agent": user_agent}
Detalles Técnicos
Header es una clase "hermana" de Path, Query y Cookie. También hereda de la misma clase común Param.
Pero recuerda que cuando importas Query, Path, Header, y otros desde fastapi, esos son en realidad funciones que retornan clases especiales.
Nota
Para declarar headers, necesitas usar Header, porque de lo contrario los parámetros serían interpretados como parámetros de query.
Conversión automática¶
Header tiene una pequeña funcionalidad extra además de lo que proporcionan Path, Query y Cookie.
La mayoría de los headers estándar están separados por un carácter "hyphen" (guion), también conocido como "símbolo de menos" (-).
Pero una variable como user-agent es inválida en Python.
Así que, por defecto, Header convertirá los caracteres de los nombres de los parámetros de underscore (_) a hyphen (-) para extraer y documentar los headers.
Además, los headers HTTP son insensibles a mayúsculas y minúsculas, así que puedes declararlos con el estilo estándar de Python (también conocido como "snake_case").
Así que puedes usar user_agent como lo harías normalmente en código Python, en lugar de necesitar capitalizar las primeras letras como User_Agent o algo similar.
Si por alguna razón necesitas deshabilitar la conversión automática de underscores a hyphens, establece el parámetro convert_underscores de Header en False:
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
strange_header: Annotated[str | None, Header(convert_underscores=False)] = None,
):
return {"strange_header": strange_header}
🤓 Otras versiones y variantes
Consejo
Preferible usar la versión con Annotated si es posible.
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
strange_header: str | None = Header(default=None, convert_underscores=False),
):
return {"strange_header": strange_header}
Aviso
Antes de establecer convert_underscores en False, ten en cuenta que algunos proxies y servidores HTTP no permiten el uso de headers con guiones bajos.
Headers duplicados¶
Es posible recibir headers duplicados. Eso significa, el mismo header con múltiples valores.
Puedes definir esos casos usando una list en la declaración de tipo.
Recibirás todos los valores del header duplicado como una list de Python.
Por ejemplo, para declarar un header X-Token que puede aparecer más de una vez, puedes escribir:
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(x_token: Annotated[list[str] | None, Header()] = None):
return {"X-Token values": x_token}
🤓 Otras versiones y variantes
Consejo
Preferible usar la versión con Annotated si es posible.
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(x_token: list[str] | None = Header(default=None)):
return {"X-Token values": x_token}
Si te comunicas con esa operación de path enviando dos headers HTTP como:
X-Token: foo
X-Token: bar
La respuesta sería algo así:
{
"X-Token values": [
"bar",
"foo"
]
}
Resumen¶
Declara headers con Header, usando el mismo patrón común que Query, Path y Cookie.
Y no te preocupes por los underscores en tus variables, FastAPI se encargará de convertirlos.