Primeros pasos
Primera API
FastAPI se construye sobre Starlette y Pydantic. uvicorn es el servidor ASGI. --reload habilita la autorrecarga durante el desarrollo.
# install FastAPI and uvicorn
pip install fastapi uvicorn
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"Hello": "World"}
# run: uvicorn main:app --reloadEjecutar con Uvicorn
La instancia de la app 'main:app' significa módulo 'main', variable 'app'. Usa --reload solo en desarrollo; en producción ejecuta sin él y usa un gestor de procesos.
# development with auto-reload
uvicorn main:app --reload
# specify host and port
uvicorn main:app --host 0.0.0.0 --port 8000
# run programmatically
import uvicorn
if __name__ == "__main__":
uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)Operaciones de ruta asíncronas
Puedes declarar operaciones de ruta con 'def' (se ejecuta en un threadpool) o 'async def'. Usa async def cuando la función haga I/O mediante librerías asíncronas; mezclar llamadas bloqueantes en async def bloqueará el event loop.
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def read_root():
return {"message": "hello"}
@app.get("/sync")
def read_sync():
return {"message": "sync also works"}
# use async when calling async libs (httpx, databases)
@app.get("/data")
async def fetch_data():
import httpx
async with httpx.AsyncClient() as client:
r = await client.get("https://api.example.com")
return r.json()Decoradores de operaciones de ruta
FastAPI soporta los distintos verbos HTTP: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD. Cada uno se mapea a un decorador. Usa status_code= en el decorador para sobrescribir el estado de éxito por defecto.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items")
def list_items(): ...
@app.post("/items")
def create_item(): ...
@app.put("/items/{item_id}")
def replace_item(item_id: int): ...
@app.patch("/items/{item_id}")
def update_item(item_id: int): ...
@app.delete("/items/{item_id}")
def delete_item(item_id: int): ...
@app.options("/items")
def options_items(): ...
@app.head("/items")
def head_items(): ...Respuesta JSON y estado
Devolver un dict/list se convierte automáticamente a JSON con 200 (o tu status_code). Para control total del estado, los headers o el contenido, devuelve un JSONResponse o Response directamente.
from fastapi import FastAPI, status
from fastapi.responses import JSONResponse
app = FastAPI()
@app.get("/plain")
def plain():
return {"key": "value"} # auto JSON, 200 OK
@app.post("/created", status_code=status.HTTP_201_CREATED)
def created():
return {"id": 1}
@app.get("/custom")
def custom():
return JSONResponse(
status_code=418,
content={"error": "I'm a teapot"},
headers={"X-Custom": "yes"},
)Estructura del proyecto
Divide una app en crecimiento en módulos con APIRouter y regístralos vía app.include_router(). Mantén los esquemas de Pydantic, la configuración de la base de datos y las dependencias en archivos separados por mantenibilidad.
myapp/
main.py # creates the FastAPI app
routers/
users.py # APIRouter for /users
items.py # APIRouter for /items
models/
schemas.py # Pydantic models
database.py # DB engine & session
dependencies.py # shared Depends functions
tests/
test_main.py
# main.py
from fastapi import FastAPI
from routers import users, items
app = FastAPI()
app.include_router(users.router)
app.include_router(items.router, prefix="/items")Parámetros de ruta
Parámetros de ruta básicos
Los valores capturados de la ruta son cadenas salvo que añadas una anotación de tipo. El nombre del parámetro en la ruta debe coincidir exactamente con el nombre del argumento de la función.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id):
return {"item_id": item_id}
# GET /items/42 -> {"item_id": "42"} (string by default)Conversión de tipos
Añadir una anotación de tipo (int, float, bool, str, Enum) hace que FastAPI valide y convierta el valor de la ruta. Los valores inválidos devuelven una respuesta 422 con un mensaje de error claro.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: int):
return {"item_id": item_id}
# GET /items/3 -> {"item_id": 3}
# GET /items/abc -> 422 Validation Error (not an integer)Validación de ruta
Path() añade metadatos y restricciones a un parámetro de ruta. Restricciones numéricas: ge (>=), gt (>), le (<=), lt (<). Los parámetros de ruta son siempre obligatorios, así que Path() no puede fijar un valor por defecto.
from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(
item_id: int = Path(
title="The ID of the item",
description="Must be a positive integer",
ge=1,
le=1000,
),
):
return {"item_id": item_id}Restricciones numéricas
Usa ge/gt/le/lt en parámetros de ruta int o float para aplicar rangos numéricos. Las restricciones combinadas te dan una validación de límites precisa con errores 422 automáticos.
from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/ratio/{value}")
def ratio(
value: float = Path(gt=0, lt=1), # 0 < value < 1
):
return {"value": value}
@app.get("/page/{page}")
def page(
page: int = Path(ge=1), # >= 1
size: int = Path(le=100), # <= 100
):
return {"page": page, "size": size}El orden de las rutas importa
Las rutas se emparejan en el orden de declaración. Declara rutas específicas como /users/me antes de patrones dinámicos como /users/{user_id}, o la ruta dinámica ocultará la específica.
from fastapi import FastAPI
app = FastAPI()
@app.get("/users/me")
def read_current_user():
return {"user": "me"}
@app.get("/users/{user_id}")
def read_user(user_id: str):
return {"user_id": user_id}
# /users/me MUST be declared before /users/{user_id}
# otherwise 'me' would match the {user_id} patternParámetros de ruta Enum
Usar un tipo Enum para un parámetro de ruta lo restringe a valores predefinidos y genera un esquema enum en la documentación OpenAPI. Hereda de (str, Enum) para que los valores se serialicen como cadenas.
from enum import Enum
from fastapi import FastAPI
class ModelName(str, Enum):
alexnet = "alexnet"
resnet = "resnet"
lenet = "lenet"
app = FastAPI()
@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
if model_name is ModelName.alexnet:
return {"model": model_name, "layers": 5}
return {"model": model_name}
# GET /models/resnet -> {"model": "resnet"}Parámetros de query
Parámetros de query básicos
Los parámetros de función que NO están en la ruta se convierten en parámetros de query. Proporcionar un valor por defecto los hace opcionales; el valor por defecto se usa cuando la clave de query está ausente.
from fastapi import FastAPI
app = FastAPI()
fake_items = [{"item": "a"}, {"item": "b"}, {"item": "c"}]
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10):
return fake_items[skip : skip + limit]
# GET /items?skip=0&limit=2
# GET /items -> skip=0, limit=10Parámetros de query opcionales
Usa Optional[str] = None (o str | None = None en Python 3.10+) para un parámetro de query que puede omitirse. Los parámetros obligatorios simplemente no tienen valor por defecto.
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: str, q: Optional[str] = None):
if q:
return {"item_id": item_id, "q": q}
return {"item_id": item_id}
# GET /items/1?q=hello
# GET /items/1 (q is None)Validación de query
Query() añade validación: min_length/max_length para cadenas, ge/gt/le/lt para números, pattern (regex) para el formato de cadena. Usa default= para fijar un valor mientras aplicas las restricciones.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/search")
def search(q: str = Query(min_length=3, max_length=50, pattern="^[a-zA-Z]+$")):
return {"q": q}
@app.get("/page")
def page(limit: int = Query(default=10, ge=1, le=100)):
return {"limit": limit}Conversión booleana
Los parámetros de query Bool aceptan muchos valores verdaderos: true, 1, yes, on (sin distinguir mayúsculas). Cualquier otra cosa se interpreta como false. Los tipos inválidos como ?active=maybe devuelven 422.
from fastapi import FastAPI
app = FastAPI()
@app.get("/flags")
def flags(active: bool = False):
return {"active": active}
# GET /flags?active=true -> {"active": true}
# GET /flags?active=1 -> {"active": true}
# GET /flags?active=yes -> {"active": true}
# GET /flags?active=off -> {"active": false}Parámetros de query de lista
Un parámetro List[str] acepta la misma clave repetida en la query string. Usa Query(default=[]) para una lista vacía por defecto, o Query(default=None) para permitir valores ausentes.
from typing import List
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items")
def list_items(q: List[str] = Query(default=[])):
return {"q": q}
# GET /items?q=a&q=b&q=c -> {"q": ["a", "b", "c"]}
# declare default=None to accept a list or nullParámetros de query obligatorios
Usa Query(...) (los puntos suspensivos) para declarar un parámetro de query obligatorio que además tenga metadatos de validación. Sin valor por defecto y sin Query(...), un parámetro anotado simple también es obligatorio.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items")
def read_item(q: str = Query(...)):
return {"q": q}
# GET /items?q=hello -> ok
# GET /items -> 422 (q is required)
# Query(...) (Ellipsis) marks a parameter as requiredCuerpo de la petición (Pydantic)
Fundamentos de BaseModel
Un BaseModel de Pydantic declarado como parámetro de función se convierte en el cuerpo JSON de la petición. FastAPI valida el payload, convierte los tipos y devuelve 422 ante datos inválidos. Los campos con valores por defecto son opcionales.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
in_stock: bool = True
app = FastAPI()
@app.post("/items")
def create_item(item: Item):
return item
# POST /items body: {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5, "in_stock": true}Tipos y restricciones de campo
Field() añade restricciones y metadatos a los atributos del modelo: min_length/max_length para cadenas, gt/ge/lt/le para números, default_factory para valores por defecto mutables. model_config con json_schema_extra añade ejemplos a la documentación.
from pydantic import BaseModel, Field
from typing import Optional
class Item(BaseModel):
name: str = Field(min_length=1, max_length=100)
price: float = Field(gt=0, description="must be positive")
tax: Optional[float] = None
tags: list[str] = Field(default_factory=list)
model_config = {
"json_schema_extra": {
"examples": [{"name": "Apple", "price": 0.5, "tags": ["fruit"]}]
}
}Modelos anidados
Los modelos pueden anidarse: declara otro BaseModel como tipo de campo. FastAPI valida toda la estructura anidada recursivamente, y el esquema OpenAPI generado refleja los objetos anidados.
from pydantic import BaseModel
from typing import Optional
class Image(BaseModel):
url: str
name: str
class Item(BaseModel):
name: str
description: Optional[str] = None
image: Optional[Image] = None
images: list[Image] = []
# valid body:
# {"name": "Phone", "image": {"url": "http://x/a.png", "name": "a"}}Validación de campos
Usa @field_validator (Pydantic v2) para añadir lógica de validación personalizada por campo. Lanza ValueError para rechazar la entrada (FastAPI la expone como 422). Devuelve el valor (posiblemente transformado) para conservarlo.
from pydantic import BaseModel, field_validator
class User(BaseModel):
name: str
email: str
@field_validator("email")
@classmethod
def email_must_contain_at(cls, v: str) -> str:
if "@" not in v:
raise ValueError("must contain @")
return v.lower()
@field_validator("name")
@classmethod
def name_stripped(cls, v: str) -> str:
return v.strip()Campos opcionales y por defecto
Un campo es obligatorio solo si no tiene valor por defecto y no es Optional. Optional[str] = None es el patrón estándar para un campo opcional nullable; un valor por defecto simple como 0.0 hace que el campo sea opcional con ese valor.
from pydantic import BaseModel
from typing import Optional
class Item(BaseModel):
name: str # required
description: Optional[str] = None # optional, defaults to None
price: float = 0.0 # optional, defaults to 0.0
tags: list[str] = [] # optional, defaults to empty list
# All of these are valid:
# {"name": "X"}
# {"name": "X", "price": 9.99, "tags": ["a"]}Body con path y query
Los parámetros de ruta, query y body pueden coexistir en una misma operación. FastAPI decide así: parámetro de ruta si está en la ruta, modelo Pydantic (o Body()) para el body, y si no, query. Un body opcional necesita un valor por defecto de None.
from fastapi import FastAPI, Path, Query
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.put("/items/{item_id}")
def update_item(
item_id: int = Path(ge=1),
q: Optional[str] = Query(default=None),
item: Item = None,
):
result = {"item_id": item_id, **item.model_dump()}
if q:
result["q"] = q
return resultModelo de respuesta
Fundamentos de response_model
response_model filtra los datos devueltos a solo los campos definidos en el modelo, incluso si devuelves un objeto con campos extra. Es la forma estándar de ocultar campos sensibles como contraseñas.
from fastapi import FastAPI
from pydantic import BaseModel
class User(BaseModel):
username: str
email: str
hashed_password: str
class UserOut(BaseModel):
username: str
email: str
app = FastAPI()
@app.get("/users/me", response_model=UserOut)
def read_user():
return User(username="bob", email="[email protected]", hashed_password="secret")
# response: {"username": "bob", "email": "[email protected]"} (no password)Excluir campos
response_model_include y response_model_exclude te permiten incluir o excluir campos por ruta sin definir modelos nuevos. Pasa un conjunto de nombres de campo. Se aplican además del response_model.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
secret: str
app = FastAPI()
@app.get("/items/{id}", response_model=Item, response_model_exclude={"secret"})
def read_item(id: int):
return {"name": "Apple", "price": 0.5, "secret": "hidden"}
@app.get("/items", response_model=list[Item], response_model_include={"name", "price"})
def list_items():
return [{"name": "Apple", "price": 0.5, "secret": "x"}]Respuesta de lista
Usa response_model=list[Model] (o List[Model]) para declarar que un endpoint devuelve un array de objetos. FastAPI valida y serializa cada ítem de la lista.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.get("/items", response_model=list[Item])
def list_items():
return [
{"name": "Apple", "price": 0.5},
{"name": "Banana", "price": 0.3},
]
# response: [{"name": "Apple", "price": 0.5}, {"name": "Banana", "price": 0.3}]Excluir no establecidos/por defecto
exclude_unset omite los campos que el cliente nunca envió (solo aparecen los establecidos explícitamente). exclude_defaults omite los campos iguales a sus valores por defecto; exclude_none omite los campos que son None. Útil para respuestas dispersas.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
description: str | None = None
price: float = 0.0
tax: float = 0.0
app = FastAPI()
@app.get("/items/{id}", response_model=Item, response_model_exclude_unset=True)
def read_item(id: int):
return {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5} (description, tax omitted)
# also: response_model_exclude_defaults=True
# response_model_exclude_none=TrueRespuesta por alias
Field(alias=...) permite que el JSON entrante use un nombre de clave distinto al del atributo de Python. response_model_by_alias=True también genera la salida usando el alias. populate_by_name=True permite además el nombre original del atributo en la entrada.
from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict, Field
class Item(BaseModel):
model_config = ConfigDict(populate_by_name=True)
name: str = Field(alias="itemName")
price: float
app = FastAPI()
@app.post("/items", response_model=Item, response_model_by_alias=True)
def create(item: Item):
return item
# input: {"itemName": "Apple", "price": 0.5}
# output: {"itemName": "Apple", "price": 0.5}Respuesta de dict plano
Devolver un dict/list se serializa automáticamente a JSON. Usa response_class para cambiar el tipo de respuesta por defecto (HTMLResponse, PlainTextResponse), o devuelve una subclase de Response directamente para control total.
from fastapi import FastAPI
from fastapi.responses import JSONResponse, PlainTextResponse
app = FastAPI()
@app.get("/dict")
def dict_resp():
return {"a": 1, "b": 2} # auto JSON
@app.get("/text", response_class=PlainTextResponse)
def text_resp():
return "plain text response"
@app.get("/raw")
def raw_resp():
return JSONResponse(content={"a": 1}, status_code=200)Formularios y UploadFile
Datos de formulario
Form() declara un parámetro parseado desde application/x-www-form-urlencoded o datos de formulario multipart. No puedes mezclar Form() con un body JSON (BaseModel) en la misma operación — elige un tipo de contenido.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login")
def login(username: str = Form(), password: str = Form()):
return {"username": username}
# Content-Type: application/x-www-form-urlencoded
# body: username=bob&password=secretUploadFile básico
UploadFile es una representación de archivo en streaming con .filename, .content_type, .read(), .write(), .close(). Usa 'await file.read()' dentro de async def. Para archivos grandes prefiere file.file (SpooledTemporaryFile) para no cargar el archivo completo en memoria.
from fastapi import FastAPI, UploadFile, File
app = FastAPI()
@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
contents = await file.read()
return {
"filename": file.filename,
"size": len(contents),
"content_type": file.content_type,
}Múltiples archivos
Declara list[UploadFile] para aceptar varios archivos en una petición. Cada archivo se envía con el mismo nombre de campo. El orden de los archivos en la lista coincide con el orden en que se enviaron.
from fastapi import FastAPI, UploadFile
app = FastAPI()
@app.post("/uploads")
async def upload_many(files: list[UploadFile]):
return [
{"filename": f.filename, "size": len(await f.read())}
for f in files
]
# curl: curl -F "[email protected]" -F "[email protected]" http://localhost:8000/uploadsArchivo y formulario juntos
Form() y UploadFile (File()) pueden combinarse en el mismo endpoint porque ambos usan multipart/form-data. Aun así no puedes combinarlos con un body BaseModel JSON.
from fastapi import FastAPI, UploadFile, File, Form
app = FastAPI()
@app.post("/items")
async def create_item(
name: str = Form(),
description: str = Form(),
file: UploadFile = File(),
):
return {
"name": name,
"description": description,
"file": file.filename,
}Guardar el archivo subido
Para archivos pequeños, shutil.copyfileobj transmite el SpooledTemporaryFile a disco de forma eficiente. Para archivos muy grandes, lee por fragmentos (por ejemplo, 1MB) para mantener la memoria baja. Sanea siempre file.filename para evitar el path traversal.
import shutil
from pathlib import Path
from fastapi import FastAPI, UploadFile
app = FastAPI()
@app.post("/save")
async def save_file(file: UploadFile):
dest = Path("uploads") / file.filename
dest.parent.mkdir(exist_ok=True)
with dest.open("wb") as buf:
shutil.copyfileobj(file.file, buf)
return {"saved_to": str(dest)}
# async alternative for large files:
# async with dest.open("wb") as buf:
# while chunk := await file.read(1024 * 1024):
# buf.write(chunk)Metadatos y tamaño del archivo
Valida file.content_type y el tamaño antes de procesar. Tras read(), el cursor está al final; llama a 'await file.seek(0)' para rebobinar si necesitas leer de nuevo. La comprobación real del tipo debería inspeccionar los magic bytes, no solo el header.
from fastapi import FastAPI, UploadFile, File
app = FastAPI()
@app.post("/validate")
async def validate(file: UploadFile = File(...)):
# allowed types
allowed = {"image/png", "image/jpeg"}
if file.content_type not in allowed:
return {"error": "unsupported type"}
contents = await file.read()
max_size = 5 * 1024 * 1024 # 5 MB
if len(contents) > max_size:
return {"error": "file too large"}
await file.seek(0) # rewind so later reads work
return {"filename": file.filename, "size": len(contents)}Inyección de dependencias
Depends básico
Depends() inyecta el valor devuelto por una función en tu operación de ruta. La lógica compartida (paginación, parseo, sesiones de base de datos) vive en un solo lugar y se reutiliza en los endpoints. Los parámetros de la dependencia también se documentan en OpenAPI.
from fastapi import FastAPI, Depends
app = FastAPI()
def common_params(q: str | None = None, skip: int = 0, limit: int = 10):
return {"q": q, "skip": skip, "limit": limit}
@app.get("/items")
def list_items(commons: dict = Depends(common_params)):
return commons
@app.get("/users")
def list_users(commons: dict = Depends(common_params)):
return commonsDependencias de clase
Una clase con __init__ puede ser una dependencia; FastAPI la llama como una función. Usa Depends(CommonQueryParams) o la forma corta Depends() cuando el parámetro está anotado con la clase. Se inyecta la instancia.
from fastapi import FastAPI, Depends
class CommonQueryParams:
def __init__(self, q: str | None = None, skip: int = 0, limit: int = 10):
self.q = q
self.skip = skip
self.limit = limit
app = FastAPI()
@app.get("/items")
def list_items(commons: CommonQueryParams = Depends(CommonQueryParams)):
return {"q": commons.q, "skip": commons.skip, "limit": commons.limit}
# shorthand: commons = Depends() infers the typeDependencias anidadas
Las dependencias pueden depender a su vez de otras dependencias, formando un grafo. FastAPI resuelve el árbol completo, cachea cada resultado por petición y propaga las excepciones. Es ideal para autenticación por capas (token -> usuario -> permisos).
from fastapi import FastAPI, Depends, Header, HTTPException
def get_token(authorization: str = Header()):
if not authorization.startswith("Bearer "):
raise HTTPException(status_code=401, detail="invalid header")
return authorization.removeprefix("Bearer ")
def get_current_user(token: str = Depends(get_token)):
if token != "admin-token":
raise HTTPException(status_code=403, detail="forbidden")
return {"username": "admin"}
app = FastAPI()
@app.get("/me")
def me(user: dict = Depends(get_current_user)):
return userDependencias con yield (limpieza)
Un generador de dependencia (yield) es perfecto para recursos que necesitan limpieza: sesiones de base de datos, manejadores de archivos, transacciones. El código después del yield corre como finalizador, incluso si la ruta lanza una excepción. Solo un yield por dependencia.
from fastapi import FastAPI, Depends
def get_db():
db = open_db_session() # acquire resource
try:
yield db # injected into the route
finally:
db.close() # always runs after the request
app = FastAPI()
@app.get("/items")
def list_items(db = Depends(get_db)):
return db.query("SELECT * FROM items")Dependencias globales
Pasa dependencies=[...] a FastAPI() (o a un APIRouter) para aplicarlas a todas las rutas sin inyectar su valor de retorno. Útil para autenticación global, rate limiting o logging de peticiones.
from fastapi import FastAPI, Depends, Header, HTTPException
def verify_token(x_token: str = Header()):
if x_token != "supersecret":
raise HTTPException(status_code=400, detail="X-Token missing")
def verify_key(x_key: str = Header()):
if x_key != "realkey":
raise HTTPException(status_code=400, detail="X-Key missing")
# applied to every route in the app
app = FastAPI(dependencies=[Depends(verify_token), Depends(verify_key)])
@app.get("/items")
def list_items():
return [{"item": "a"}] # token & key already checkedDependencias por ruta
Usa dependencies=[Depends(...)] en un decorador (o APIRouter) para exigir una dependencia en rutas concretas sin usar su valor de retorno. Así las firmas de las rutas se mantienen limpias mientras se aplican las comprobaciones.
from fastapi import FastAPI, Depends, Header, HTTPException
def verify_token(x_token: str = Header()):
if x_token != "secret":
raise HTTPException(status_code=401, detail="bad token")
app = FastAPI()
@app.get("/public")
def public():
return {"open": True}
@app.get("/private", dependencies=[Depends(verify_token)])
def private():
return {"secret": "data"}Seguridad (HTTPBasic / OAuth2 / JWT)
Autenticación HTTP Basic
HTTPBasic parsea el header Authorization: Basic en usuario/contraseña. Usa secrets.compare_digest (no ==) para evitar ataques de temporización. Devuelve siempre 401 con WWW-Authenticate: Basic para que los navegadores pidan credenciales.
import secrets
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials
security = HTTPBasic()
app = FastAPI()
def get_current_user(credentials: HTTPBasicCredentials = Depends(security)):
correct_user = secrets.compare_digest(credentials.username, "admin")
correct_pass = secrets.compare_digest(credentials.password, "secret")
if not (correct_user and correct_pass):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid credentials",
headers={"WWW-Authenticate": "Basic"},
)
return credentials.username
@app.get("/profile")
def profile(user: str = Depends(get_current_user)):
return {"user": user}OAuth2PasswordBearer
OAuth2PasswordBearer declara que las rutas esperan un token Bearer; la dependencia lo extrae del header Authorization. tokenUrl indica a la interfaz de documentación dónde enviar las credenciales. El token en sí es solo una cadena hasta que lo validas.
from fastapi import FastAPI, Depends
from fastapi.security import OAuth2PasswordBearer
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
app = FastAPI()
@app.get("/me")
def me(token: str = Depends(oauth2_scheme)):
return {"token": token}
# client POSTs username+password to /token, receives an access token,
# then sends it as: Authorization: Bearer <token>Crear token JWT
Usa python-jose (o PyJWT) para firmar tokens. El claim 'sub' (subject) contiene por convención el nombre de usuario o el id del usuario, y 'exp' fija la expiración. Mantén SECRET_KEY largo, aleatorio y cargado desde el entorno — nunca lo subas al repositorio.
from datetime import datetime, timedelta, timezone
from jose import jwt
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"
def create_access_token(data: dict, expires_minutes: int = 30) -> str:
to_encode = data.copy()
expire = datetime.now(timezone.utc) + timedelta(minutes=expires_minutes)
to_encode.update({"exp": expire})
return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
# token = create_access_token({"sub": "alice"})
# -> eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Decodificar token JWT
jwt.decode verifica la firma y el claim 'exp' automáticamente, lanzando JWTError en caso de fallo. Mapea la dependencia a un 401 con WWW-Authenticate: Bearer para que los clientes sepan que deben proporcionar un token válido.
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import jwt, JWTError
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"
def get_current_user(token: str = Depends(oauth2_scheme)) -> str:
try:
payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
username: str | None = payload.get("sub")
if username is None:
raise credentials_exception
return username
except JWTError:
raise credentials_exception
credentials_exception = HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
)Hasheado de contraseñas
Nunca almacenes contraseñas en texto plano. passlib con bcrypt (o argon2) maneja el salting y el hasheado. verify() compara una entrada en texto plano contra un hash guardado. pip install passlib[bcrypt] para obtener el backend bcrypt.
from passlib.context import CryptContext
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
def hash_password(plain: str) -> str:
return pwd_context.hash(plain)
def verify_password(plain: str, hashed: str) -> bool:
return pwd_context.verify(plain, hashed)
# usage when issuing tokens:
def authenticate_user(username: str, password: str):
user = fake_db.get(username)
if not user or not verify_password(password, user.hashed_password):
return False
return userFlujo de login OAuth2
OAuth2PasswordRequestForm lee usuario/contraseña de un POST codificado como formulario (el flujo estándar de contraseña OAuth2). Devuelve access_token y token_type: 'bearer'. Este endpoint es al que apunta tokenUrl en OAuth2PasswordBearer.
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
app = FastAPI()
@app.post("/token")
def login(form: OAuth2PasswordRequestForm = Depends()):
user = authenticate_user(form.username, form.password)
if not user:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Incorrect username or password",
)
token = create_access_token({"sub": user.username})
return {"access_token": token, "token_type": "bearer"}
# OAuth2PasswordRequestForm parses username+password from form data
# and powers the 'Authorize' button in the Swagger UI.Middleware
Añadir middleware
@app.middleware('http') registra una función que envuelve cada petición. Debe hacer await call_next(request) para obtener la respuesta, y luego puede inspeccionarla o modificarla antes de devolverla. El middleware corre para todas las rutas.
import time
from fastapi import FastAPI, Request
app = FastAPI()
@app.middleware("http")
async def add_process_time(request: Request, call_next):
start = time.perf_counter()
response = await call_next(request)
duration = time.perf_counter() - start
response.headers["X-Process-Time"] = f"{duration:.4f}"
return responseMiddleware de header personalizado
El middleware es el lugar adecuado para adjuntar headers que deban ir en cada respuesta (headers de seguridad, banner del servidor, IDs de trazado). Muta el objeto de respuesta tras el await de call_next.
from fastapi import FastAPI, Request
app = FastAPI()
@app.middleware("http")
async def add_banner(request: Request, call_next):
response = await call_next(request)
response.headers["X-Powered-By"] = "FastAPI"
response.headers["X-Frame-Options"] = "DENY"
return response
# every response now carries these headersBaseHTTPMiddleware
Para middleware reutilizable y configurable, hereda de BaseHTTPMiddleware y regístralo con app.add_middleware(MyMiddleware, **options). Así se añaden también los middlewares integrados CORS, GZip y TrustedHost.
from starlette.middleware.base import BaseHTTPMiddleware
from fastapi import FastAPI, Request
class TimingMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
start = time.perf_counter()
response = await call_next(request)
response.headers["X-Duration"] = str(time.perf_counter() - start)
return response
app = FastAPI()
app.add_middleware(TimingMiddleware)
# class-based middleware is reusable and configurableRedirección HTTPS
HTTPSRedirectMiddleware devuelve una redirección 308 a la versión HTTPS de cualquier petición HTTP. Úsalo detrás de un balanceador que termina el TLS, para garantizar que los clientes actualicen a una conexión segura.
from fastapi import FastAPI
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
app = FastAPI()
app.add_middleware(HTTPSRedirectMiddleware)
# all HTTP requests are redirected to HTTPS (308)Host de confianza
TrustedHostMiddleware rechaza las peticiones cuyo header Host no esté en la lista permitida, previniendo ataques de inyección de header Host. Se soportan comodines como '*.example.com'. Incluye siempre 'localhost' para el desarrollo local.
from fastapi import FastAPI
from fastapi.middleware.trustedhost import TrustedHostMiddleware
app = FastAPI()
app.add_middleware(
TrustedHostMiddleware,
allowed_hosts=["example.com", "*.example.com", "localhost"],
)
# requests with a disallowed Host header get a 400 responseOrden del middleware
Starlette ejecuta el middleware en orden LIFO para las peticiones entrantes: el último añadido corre primero. Añade CORS temprano (para que el preflight funcione) y GZip después. Recuérdalo al depurar por qué un header fijado por un middleware no lo ve otro.
from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
# Middleware runs in REVERSE order of registration for requests,
# and in registration order for responses.
app.add_middleware(GZipMiddleware, minimum_size=1000)
app.add_middleware(CORSMiddleware, allow_origins=["*"])
# request flow: CORS -> GZip -> route
# response flow: route -> GZip -> CORSCORS
Configuración de CORSMiddleware
CORSMiddleware maneja el preflight de CORS (OPTIONS) y añade los headers Access-Control-*. allow_origins debería listar los orígenes exactos permitidos; usa una lista de URLs específicas en producción en lugar de ['*'].
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://example.com", "https://www.example.com"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
@app.get("/api/data")
def data():
return {"data": 1}Permitir cualquier origen (solo dev)
allow_origins=['*'] permite cualquier origen pero no puede combinarse con allow_credentials=True (los navegadores lo rechazan). Úsalo solo para APIs totalmente públicas en desarrollo; en producción enumera los orígenes reales.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
# allow_credentials=True CANNOT be combined with allow_origins=["*"]
)Permitir credenciales
allow_credentials=True permite al navegador enviar cookies y headers Authorization entre orígenes. Requiere orígenes específicos (nunca '*'). El navegador fija Access-Control-Allow-Credentials: true en las respuestas.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_credentials=True, # send cookies / Authorization
allow_methods=["GET", "POST"],
allow_headers=["Authorization", "Content-Type"],
)
# needed when the frontend sends cookies or credentials with requestsVerbos y headers permitidos
allow_methods/allow_headers restringen lo que el navegador puede enviar. expose_headers lista los headers de respuesta que el JavaScript del frontend puede leer (de lo contrario los navegadores ocultan los headers personalizados). Las respuestas de preflight las cachea el navegador.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
expose_headers=["X-Total-Count", "X-Process-Time"],
)
# expose_headers lets the frontend JS read these response headersPeticiones de preflight
Para peticiones 'no simples' (por ejemplo, headers personalizados, PUT/DELETE, content type JSON), el navegador envía un preflight OPTIONS. CORSMiddleware intercepta el OPTIONS y responde con los verbos/headers permitidos. max_age controla cuánto tiempo cachea el navegador esa respuesta.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_methods=["*"],
allow_headers=["*"],
max_age=600, # browser caches preflight result for 600s
)
# Browser sends OPTIONS preflight for non-simple requests;
# CORSMiddleware answers automatically with the right headers.Validación dinámica de orígenes
Para listas permitidas dinámicas usa allow_origin_regex (compara contra el Origin de la petición) en lugar de una lista estática. Es práctico cuando los orígenes válidos siguen un patrón (por ejemplo, cualquier subdominio de example.com).
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
VALID_DOMAINS = {"example.com", "staging.example.com"}
def origin_check(origin: str) -> str | None:
if origin and origin.replace("https://", "").replace("http://", "") in VALID_DOMAINS:
return origin
return None
app.add_middleware(
CORSMiddleware,
allow_origin_regex=r"https://.*\.example\.com",
allow_methods=["*"],
allow_headers=["*"],
)Manejo de excepciones
Lanzar HTTPException
Lanza HTTPException en cualquier parte de una ruta o dependencia para cortocircuitar y devolver una respuesta de error. detail puede ser una cadena, un dict o una lista — se convierte en el campo 'detail' del JSON. headers añade opcionalmente headers de respuesta.
from fastapi import FastAPI, HTTPException, status
app = FastAPI()
items = {1: "Apple", 2: "Banana"}
@app.get("/items/{item_id}")
def read_item(item_id: int):
if item_id not in items:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="Item not found",
headers={"X-Error": "missing"},
)
return {"item": items[item_id]}Excepción personalizada
Registra un manejador con @app.exception_handler(MyException) para convertir cualquier excepción personalizada en una respuesta HTTP. El manejador recibe la petición y la excepción. Esto centraliza el formato de errores de las excepciones de tu dominio.
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
class UnicornException(Exception):
def __init__(self, name: str):
self.name = name
app = FastAPI()
@app.exception_handler(UnicornException)
async def unicorn_handler(request: Request, exc: UnicornException):
return JSONResponse(
status_code=418,
content={"message": f"Oops, {exc.name} did it again"},
)
@app.get("/unicorns/{name}")
def read_unicorn(name: str):
if name == "yolo":
raise UnicornException(name=name)
return {"name": name}Sobrescribir el error de validación
RequestValidationError se lanza cuando la entrada falla la validación de Pydantic. Sobrescribe su manejador con @app.exception_handler(RequestValidationError) para personalizar la forma de la respuesta 422, por ejemplo para ajustarte a un envoltorio de error corporativo.
from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
app = FastAPI()
@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
return JSONResponse(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
content={
"success": False,
"errors": exc.errors(),
"body": exc.body,
},
)Sobrescribir el manejador de HTTPException
Sobrescribe el manejador por defecto de HTTPException para imponer una forma de JSON de error consistente en todas las HTTPException lanzadas. Importa la clase como fastapi.exceptions.HTTPException (la misma que usa raise) al reasignar su manejador.
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException as FastAPIHTTPException
app = FastAPI()
@app.exception_handler(FastAPIHTTPException)
async def custom_http_handler(request, exc: FastAPIHTTPException):
return JSONResponse(
status_code=exc.status_code,
content={
"success": False,
"status": exc.status_code,
"message": exc.detail,
},
headers=exc.headers,
)Códigos de estado comunes
El módulo status da constantes con nombre para los códigos de estado HTTP, evitando números mágicos. 200 (GET por defecto), 201 (creado), 204 (sin contenido), 422 (validación) son los más comunes en apps de FastAPI.
from fastapi import FastAPI, status
app = FastAPI()
@app.get("/ok", status_code=status.HTTP_200_OK)
def ok(): return {"ok": True}
@app.post("/create", status_code=status.HTTP_201_CREATED)
def create(): return {"id": 1}
@app.get("/no-content", status_code=status.HTTP_204_NO_CONTENT)
def no_content(): return None
@app.get("/not-found")
def missing():
# raise HTTPException(status.HTTP_404_NOT_FOUND, "nope")
...
# Other common: 400 BAD_REQUEST, 401 UNAUTHORIZED,
# 403 FORBIDDEN, 409 CONFLICT, 422 UNPROCESSABLE_ENTITY, 500 INTERNAL_SERVER_ERRORManejador de excepciones genérico
Registrar un manejador para la clase base Exception captura aquello que no esté ya manejado, evitando que los stack traces se filtren a los clientes. Registra siempre el traceback completo en el servidor; devuelve un 500 genérico al cliente.
import logging
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
logger = logging.getLogger("uvicorn.error")
app = FastAPI()
@app.exception_handler(Exception)
async def unhandled(request: Request, exc: Exception):
logger.exception("Unhandled error on %s", request.url.path)
return JSONResponse(
status_code=500,
content={"detail": "Internal Server Error"},
)
@app.get("/boom")
def boom():
raise RuntimeError("something exploded")Tareas en segundo plano
BackgroundTasks básico
BackgroundTasks ejecuta funciones después de enviar la respuesta — perfecto para trabajo fire-and-forget como logging, correos o invalidación de caché. add_task programa una función (y sus argumentos) sin bloquear la respuesta.
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
def write_log(message: str):
with open("log.txt", "a") as f:
f.write(message + "\n")
@app.post("/send")
def send_notification(background_tasks: BackgroundTasks):
background_tasks.add_task(write_log, "notification sent")
return {"message": "notification queued"}Varias tareas
Añade tantas tareas como quieras; corren secuencialmente en el orden añadido, tras devolver la respuesta. Como corren en el mismo proceso, mantenlas rápidas y no bloqueantes, o pásalas a una cola real (Celery, RQ, Dramatiq).
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
def send_email(to: str, subject: str): ...
def update_cache(key: str): ...
def notify_slack(msg: str): ...
@app.post("/signup")
def signup(background_tasks: BackgroundTasks):
background_tasks.add_task(send_email, "[email protected]", "Welcome")
background_tasks.add_task(update_cache, "user_count")
background_tasks.add_task(notify_slack, "new signup")
return {"status": "ok"}Tarea con dependencias
BackgroundTasks se inyecta como cualquier dependencia. La función de tarea puede recibir valores (como una sesión de base de datos) capturados en el momento de la petición. Ten en cuenta que los recursos obtenidos por yield/cerrados de las dependencias se cierran tras terminar las tareas, ya que las tareas corren dentro del ámbito del ciclo de vida de la petición.
from fastapi import FastAPI, BackgroundTasks, Depends
app = FastAPI()
def get_db_session():
db = "session"
yield db
def write_log(db, message: str):
print(db, message)
@app.get("/items")
def list_items(background_tasks: BackgroundTasks, db = Depends(get_db_session)):
background_tasks.add_task(write_log, db, "list called")
return {"items": []}Función de tarea asíncrona
Las funciones de tarea en segundo plano pueden ser sincrónicas (corren en un threadpool) o asíncronas (esperadas en el event loop). Usa tareas async para trabajo limitado por I/O que use librerías asíncronas, y tareas sync para trabajo de CPU/bloqueante.
from fastapi import FastAPI, BackgroundTasks
import httpx
app = FastAPI()
async def fetch_url(url: str):
async with httpx.AsyncClient() as client:
r = await client.get(url)
return r.status_code
@app.post("/webhook")
def webhook(url: str, background_tasks: BackgroundTasks):
background_tasks.add_task(fetch_url, url)
return {"queued": url}Background vs Celery
Usa BackgroundTasks para trabajo ligero y no crítico que pueda perderse al reiniciar. Para trabajos que deban sobrevivir a fallos, reintentarse o escalar entre máquinas, usa una cola de tareas real (Celery, RQ, Dramatiq, Arq) con un broker como Redis o RabbitMQ.
# BackgroundTasks: in-process, no broker, lost if process crashes
@app.post("/quick")
def quick(tasks: BackgroundTasks):
tasks.add_task(small_job)
return {"ok": True}
# Celery/RQ/Dramatiq: separate workers, persistent, retryable
# from celery import Celery
# @celery.task
# def big_job(payload): ...
#
# @app.post("/heavy")
# def heavy(payload: dict):
# big_job.delay(payload)
# return {"queued": True}Ejemplo de envío de correo
El envío de correo es el caso de uso clásico de BackgroundTasks: es lento y el usuario no debería esperar. La respuesta vuelve de inmediato mientras el correo se envía después. Para alto volumen, prefiere una cola y un SDK de servicio de correo con reintentos.
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel, EmailStr
class Message(BaseModel):
to: EmailStr
subject: str
body: str
app = FastAPI()
def send_email(to: str, subject: str, body: str):
# smtplib or your provider's SDK
import smtplib
with smtplib.SMTP("localhost") as s:
s.sendmail("[email protected]", to, f"Subject: {subject}\n\n{body}")
@app.post("/contact")
def contact(msg: Message, tasks: BackgroundTasks):
tasks.add_task(send_email, msg.to, msg.subject, msg.body)
return {"status": "queued", "to": msg.to}WebSocket
WebSocket básico
Usa @app.websocket() para definir un endpoint WebSocket. Debes hacer accept() de la conexión antes de enviar/recibir. La función normalmente itera leyendo mensajes; receive_text/receive_bytes/receive_json esperan datos del cliente.
from fastapi import FastAPI, WebSocket
app = FastAPI()
@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
await ws.accept()
while True:
data = await ws.receive_text()
await ws.send_text(f"echo: {data}")
# client (browser):
# const ws = new WebSocket("ws://localhost:8000/ws");
# ws.onmessage = (e) => console.log(e.data);Enviar JSON
send_json() y receive_json() manejan la serialización por ti, intercambiando objetos JSON por el socket. Para datos binarios usa send_bytes/receive_bytes. Cada send/receive es un fotograma aparte en el WebSocket.
import json
from fastapi import FastAPI, WebSocket
app = FastAPI()
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
await ws.accept()
while True:
msg = await ws.receive_json()
await ws.send_json({"reply": msg.get("text", "").upper()})
# send_text / send_bytes / send_json helpers are availableCerrar el WebSocket
WebSocketDisconnect se lanza cuando el cliente cierra la conexión — captúralo para limpiar. Llama a ws.close(code=1000) para un cierre normal; los códigos comunes son 1000 (normal), 1008 (violación de política), 1011 (error del servidor).
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
app = FastAPI()
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
await ws.accept()
try:
while True:
data = await ws.receive_text()
if data == "quit":
await ws.close(code=1000)
break
await ws.send_text(data)
except WebSocketDisconnect:
print("client disconnected")Gestor de conexiones
Un ConnectionManager sigue los sockets activos para que puedas hacer broadcast a cada cliente conectado (por ejemplo, una sala de chat). Elimina siempre el socket al desconectarse para no enviar a conexiones cerradas y mantener la memoria acotada.
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
class ConnectionManager:
def __init__(self):
self.active: list[WebSocket] = []
async def connect(self, ws: WebSocket):
await ws.accept()
self.active.append(ws)
def disconnect(self, ws: WebSocket):
self.active.remove(ws)
async def broadcast(self, message: str):
for ws in self.active:
await ws.send_text(message)
manager = ConnectionManager()
app = FastAPI()
@app.websocket("/chat")
async def chat(ws: WebSocket):
await manager.connect(ws)
try:
while True:
msg = await ws.receive_text()
await manager.broadcast(msg)
except WebSocketDisconnect:
manager.disconnect(ws)Autenticación del WebSocket vía query param
Los navegadores no pueden fijar headers personalizados en conexiones WebSocket, así que los tokens de autenticación suelen pasarse como parámetros de query (o cookies). Valida antes de llamar a accept(), y cierra con código 1008 (violación de política) si no está autorizado.
from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException
app = FastAPI()
async def authenticate(token: str) -> str:
if token != "secret":
raise HTTPException(status_code=401)
return "alice"
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
token = ws.query_params.get("token")
if not token:
await ws.close(code=1008)
return
user = await authenticate(token)
await ws.accept()
try:
while True:
data = await ws.receive_text()
await ws.send_text(f"{user}: {data}")
except WebSocketDisconnect:
passWebSocket con dependencias
Las dependencias pueden usarse en endpoints WebSocket igual que en rutas HTTP, pero solo tienen sentido las dependencias que leen del handshake inicial (headers, parámetros de query, cookies) — no hay body. Inyéctalas vía Depends() como de costumbre.
from fastapi import FastAPI, WebSocket, Depends, Header
app = FastAPI()
def token_validator(token: str = Header(default="")):
# for WS, headers come from the initial HTTP handshake
return token == "valid"
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket, valid: bool = Depends(token_validator)):
if not valid:
await ws.close(code=1008)
return
await ws.accept()
while True:
msg = await ws.receive_text()
await ws.send_text(msg)Base de datos (SQLAlchemy)
Configuración de SQLAlchemy
create_engine configura el pool de conexiones de la base de datos; SessionLocal es una factoría de sesiones; Base es la base declarativa para los modelos. Para SQLite con FastAPI, fija check_same_thread=False porque las peticiones pueden correr en distintos hilos.
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base
SQLALCHEMY_DATABASE_URL = "sqlite:///./app.db"
# postgresql: "postgresql://user:pass@localhost:5432/dbname"
engine = create_engine(
SQLALCHEMY_DATABASE_URL,
connect_args={"check_same_thread": False}, # sqlite only
)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base = declarative_base()Dependencia de sesión
Una dependencia con yield es la forma canónica de proporcionar una sesión de base de datos: cada petición obtiene una sesión nueva que se cierra en el bloque finally. Esto garantiza la limpieza incluso si la ruta lanza una excepción.
from fastapi import Depends
from sqlalchemy.orm import Session
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
@app.get("/items")
def list_items(db: Session = Depends(get_db)):
return db.query(Item).all()
# each request gets its own session, closed automatically afterwardDefinición de modelos
Define las tablas como modelos ORM de SQLAlchemy que heredan de Base. Usa Alembic para las migraciones de esquema en producción en lugar de create_all(). Las columnas pueden indexarse, ser nullable y tener valores por defecto aplicados a nivel de base de datos o de Python.
from sqlalchemy import Column, Integer, String, Boolean
from sqlalchemy.orm import declarative_base
Base = declarative_base()
class Item(Base):
__tablename__ = "items"
id = Column(Integer, primary_key=True, index=True)
name = Column(String, index=True, nullable=False)
price = Column(Integer, default=0)
in_stock = Column(Boolean, default=True)
# create tables (for dev; use Alembic migrations in prod)
Base.metadata.create_all(bind=engine)Crear registro
add() prepara una fila nueva, commit() la escribe en la base de datos, y refresh() recarga la instancia con los valores generados por el servidor (como el id autoincremental). Envuelve varias escrituras en una transacción y haz commit una vez al final.
from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session
app = FastAPI()
@app.post("/items", status_code=201)
def create_item(payload: ItemCreate, db: Session = Depends(get_db)):
item = Item(name=payload.name, price=payload.price)
db.add(item)
db.commit()
db.refresh(item) # load generated id
return itemConsultar registros
db.query(Model) inicia una consulta; .filter() aplica condiciones WHERE, .offset()/.limit() pagina, .first() devuelve una fila o None, .all() devuelve una lista. Usa .filter_by(name=x) para condiciones de igualdad simples.
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
app = FastAPI()
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
return db.query(Item).offset(skip).limit(limit).all()
@app.get("/items/{item_id}")
def get_item(item_id: int, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if not item:
raise HTTPException(status_code=404, detail="not found")
return itemActualizar y eliminar
Para actualizaciones parciales, itera model_dump(exclude_unset=True) para que solo cambien los campos proporcionados. delete() prepara la eliminación; commit() la finaliza. Devuelve 204 No Content para DELETE en caso de éxito.
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
app = FastAPI()
@app.put("/items/{item_id}")
def update_item(item_id: int, payload: ItemUpdate, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if not item:
raise HTTPException(status_code=404, detail="not found")
for k, v in payload.model_dump(exclude_unset=True).items():
setattr(item, k, v)
db.commit()
db.refresh(item)
return item
@app.delete("/items/{item_id}", status_code=204)
def delete_item(item_id: int, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if item:
db.delete(item)
db.commit()Base de datos (Tortoise ORM)
Configuración de Tortoise
Tortoise ORM es asíncrono nativo, emparejando bien con FastAPI. Inicialízalo al arrancar con db_url y el/los módulos que contengan tus modelos. generate_schemas() está bien para desarrollo; usa Aerich para migraciones en producción. Usa el manejador lifespan en lugar de on_event en código nuevo.
from fastapi import FastAPI
from tortoise import Tortoise
app = FastAPI()
async def init():
await Tortoise.init(
db_url="sqlite://db.sqlite3",
modules={"models": ["app.models"]},
)
await Tortoise.generate_schemas()
@app.on_event("startup")
async def startup():
await init()
@app.on_event("shutdown")
async def shutdown():
await Tortoise.close_connections()Definición de modelos
Los modelos de Tortoise heredan de Model y declaran campos vía tortoise.fields. Los tipos de campo se mapean a tipos de columna de la base de datos. Fija el nombre de la tabla en la clase Meta interna. Las relaciones usan ForeignKeyField, ManyToManyField, etc.
from tortoise import fields
from tortoise.models import Model
class Item(Model):
id = fields.IntField(pk=True)
name = fields.CharField(max_length=100)
price = fields.FloatField(default=0.0)
created_at = fields.DatetimeField(auto_now_add=True)
class Meta:
table = "items"
def __str__(self):
return self.nameCrear registro
Item.create() es una corrutina que inserta y devuelve la fila nueva. Para devolver una respuesta Pydantic, construye un BaseModel con from_tortoise_orm() (vía tortoise.contrib.pydantic) para que Tortoise serialice correctamente las relaciones cargadas de forma asíncrona.
from fastapi import FastAPI
from pydantic import BaseModel
from .models import Item
app = FastAPI()
class ItemIn(BaseModel):
name: str
price: float
@app.post("/items", response_model=ItemOut, status_code=201)
async def create_item(payload: ItemIn):
item = await Item.create(name=payload.name, price=payload.price)
return await ItemOut.from_tortoise_orm(item)Consulta asíncrona
Las consultas de Tortoise se esperan: .all() devuelve un queryset, .filter() añade condiciones, .get_or_none() obtiene una fila o None, .first() devuelve la primera coincidencia. Evita .get() salvo que esperes exactamente una fila (lanza error si no la encuentra).
from fastapi import FastAPI, HTTPException
from .models import Item
app = FastAPI()
@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
return await Item.all().offset(skip).limit(limit)
@app.get("/items/{item_id}")
async def get_item(item_id: int):
item = await Item.get_or_none(id=item_id)
if not item:
raise HTTPException(status_code=404, detail="not found")
return itemActualizar y eliminar
Modifica los atributos del modelo y luego await save() para actualizar una fila, o await Item.filter(id=...).update(name=x) para actualizaciones masivas. await item.delete() elimina la fila. Cada función es una corrutina y debe esperarse.
from fastapi import FastAPI, HTTPException
from .models import Item
app = FastAPI()
@app.put("/items/{item_id}")
async def update_item(item_id: int, name: str):
item = await Item.get_or_none(id=item_id)
if not item:
raise HTTPException(status_code=404, detail="not found")
item.name = name
await item.save()
return item
@app.delete("/items/{item_id}", status_code=204)
async def delete_item(item_id: int):
item = await Item.get_or_none(id=item_id)
if item:
await item.delete()Esquemas Pydantic de Tortoise
tortoise.contrib.pydantic genera modelos Pydantic directamente a partir de los modelos de Tortoise, así que no mantienes dos esquemas. Usa pydantic_model_creator para un solo objeto y pydantic_queryset_creator para una respuesta de lista.
from tortoise.contrib.pydantic import pydantic_model_creator, pydantic_queryset_creator
from .models import Item
ItemOut = pydantic_model_creator(Item, name="ItemOut")
ItemList = pydantic_queryset_creator(Item)
@app.get("/items", response_model=ItemList)
async def list_items():
return await Item.all()
# auto-generates a Pydantic model from the Tortoise model,
# including types and docstrings.Pruebas (TestClient)
TestClient básico
TestClient envuelve tu app y te permite hacer peticiones en el proceso (sin socket real). Se basa en httpx y funciona con pytest de inmediato. Importa la misma instancia de app que ejecutas en producción.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_root():
response = client.get("/")
assert response.status_code == 200
assert response.json() == {"Hello": "World"}
# TestClient is based on httpx; no network is involved —
# it calls the ASGI app directly in-process.Probar GET y POST
Pasa json= para bodies JSON, params= para parámetros de query, headers= para headers y files= para subidas multipart. Los fallos de validación devuelven 422 — haz aserciones sobre status_code y la estructura del 'detail' del error.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_create_item():
response = client.post(
"/items",
json={"name": "Apple", "price": 0.5},
)
assert response.status_code == 201
assert response.json()["name"] == "Apple"
def test_validation_error():
response = client.post("/items", json={"name": "Apple"}) # missing price
assert response.status_code == 422Fixture de pytest
Un fixture de pytest que devuelva un TestClient mantiene las pruebas DRY y permite a cada prueba obtener un cliente nuevo. Para pruebas con base de datos, añade un fixture que cree/elimine tablas o use un rollback de transacción por prueba para mantenerlas aisladas.
import pytest
from fastapi.testclient import TestClient
from main import app
@pytest.fixture
def client():
return TestClient(app)
def test_read(client):
r = client.get("/items")
assert r.status_code == 200
def test_create(client):
r = client.post("/items", json={"name": "X"})
assert r.status_code == 201
# run: pytest -vSobrescribir dependencias
app.dependency_overrides intercambia una dependencia (como la sesión real de base de datos o la autenticación) por un mock/fake durante las pruebas, sin cambiar las rutas. Es la forma canónica de probar endpoints aislados de servicios externos. Límpialo después de las pruebas.
from fastapi.testclient import TestClient
from main import app, get_db
def get_test_db():
# return a test session or mock
yield FakeSession()
app.dependency_overrides[get_db] = get_test_db
client = TestClient(app)
def test_items():
r = client.get("/items")
assert r.status_code == 200
# restore afterwards:
app.dependency_overrides.clear()Probar la autenticación
OAuth2PasswordRequestForm espera datos codificados como formulario (data=, no json=). Usa el token devuelto en el header Authorization: Bearer para las peticiones protegidas siguientes. Para saltarte la autenticación por completo, sobrescribe en su lugar la dependencia get_current_user.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def get_token():
r = client.post(
"/token",
data={"username": "admin", "password": "secret"},
)
return r.json()["access_token"]
def test_protected():
token = get_token()
r = client.get(
"/me",
headers={"Authorization": f"Bearer {token}"},
)
assert r.status_code == 200
assert r.json()["username"] == "admin"Probar WebSocket
TestClient.websocket_connect() abre un WebSocket dentro de un context manager. Usa send_text/receive_text (y las variantes json/bytes) para intercambiar mensajes. Recibir sobre una conexión cerrada lanza WebSocketDisconnect.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_websocket():
with client.websocket_connect("/ws") as ws:
ws.send_text("hello")
data = ws.receive_text()
assert data == "echo: hello"
def test_websocket_close():
with client.websocket_connect("/ws") as ws:
ws.send_text("quit")
# the server closes the connectionDocumentación OpenAPI
Swagger UI
FastAPI genera automáticamente una Swagger UI interactiva en /docs a partir de tus rutas, tipos y docstrings. Fija title/description/version en la app, y añade un docstring o summary/description en cada ruta para enriquecer la interfaz.
from fastapi import FastAPI
app = FastAPI(
title="My API",
description="Sample API with auto docs",
version="1.0.0",
)
@app.get("/items", summary="List items", description="Returns all items")
def list_items():
"""Get every item in the catalog."""
return [{"id": 1}]
# interactive docs at: http://localhost:8000/docsReDoc
ReDoc en /redoc es una alternativa de solo lectura centrada en la documentación. El esquema OpenAPI crudo vive en /openapi.json y puede alimentar otras herramientas. Desactiva la documentación con docs_url=None, redoc_url=None, openapi_url=None (por ejemplo, en producción).
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def root():
return {"hello": "world"}
# ReDoc (alternative docs UI) at: http://localhost:8000/redoc
# raw OpenAPI JSON at: http://localhost:8000/openapi.json
# disable docs entirely:
# app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)Tags y agrupación
Los tags agrupan rutas en la interfaz de documentación. Predeclara los metadatos de tag (name, description, externalDocs) en openapi_tags para que el grupo aparezca incluso antes de que cualquier ruta lo use. Fija deprecated=True para marcar un endpoint como obsoleto en la documentación.
from fastapi import FastAPI
app = FastAPI(openapi_tags=[
{"name": "users", "description": "User management"},
{"name": "items", "description": "Item operations"},
])
@app.get("/users", tags=["users"])
def list_users(): ...
@app.post("/items", tags=["items"])
def create_item(): ...
@app.get("/items/{id}", tags=["items"], deprecated=True)
def get_item(id: int): ...Metadatos de ruta
Los decoradores aceptan metadatos que fluyen a OpenAPI: summary (título corto), description (texto largo), response_description, tags, deprecated y status_code. Un docstring se usa como description si no pasas uno explícitamente.
from fastapi import FastAPI, status
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.post(
"/items",
response_model=Item,
status_code=status.HTTP_201_CREATED,
summary="Create an item",
description="Creates a new item and returns it.",
tags=["items"],
response_description="The created item",
)
def create_item(item: Item):
"""Create endpoint docstring — also shown in docs."""
return itemEjemplos de campos
Field(examples=[...]) y Body(examples=[...]) añaden payloads de ejemplo al 'Try it out' y al desplegable de ejemplos de la Swagger UI. Los ejemplos de Body pueden incluir varios casos con resúmenes para mostrar entradas válidas e inválidas.
from pydantic import BaseModel, Field
from fastapi import FastAPI, Body
class Item(BaseModel):
name: str = Field(examples=["Apple"])
price: float = Field(examples=[0.5], gt=0)
app = FastAPI()
@app.post("/items")
def create_item(item: Item):
return item
@app.post("/manual")
def manual(
item: Item = Body(
examples=[
{"summary": "valid", "value": {"name": "Apple", "price": 0.5}},
{"summary": "invalid", "value": {"name": "Apple", "price": -1}},
],
),
):
return itemEsquema OpenAPI personalizado
Sobrescribe app.openapi para personalizar el esquema generado — añade un logo, metadatos extra, o elimina/transforma operaciones. Cachea el resultado en app.openapi_schema para que solo se genere una vez. El esquema es lo que sirve /openapi.json.
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
schema = get_openapi(
title="Custom API",
version="2.0.0",
routes=app.routes,
)
schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
app.openapi_schema = schema
return schema
app.openapi = custom_openapiDespliegue (Uvicorn / Gunicorn)
Uvicorn en producción
Para producción, ejecuta Uvicorn detrás de un proxy inverso (Nginx, Caddy, un balanceador en la nube). Usa --proxy-headers para que la app vea la IP/host real del cliente desde X-Forwarded-For/X-Forwarded-Proto. Evita --reload en producción.
# Run directly with uvicorn (single worker)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1
# Recommended: behind a reverse proxy (nginx) on port 8000
# Use --proxy-headers so X-Forwarded-* is trusted
uvicorn main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips='*'Gunicorn con workers Uvicorn
Gunicorn gestiona varios procesos worker de Uvicorn, dándote recargas elegantes, reinicios ante fallos y escalado pre-fork. Usa la clase UvicornWorker. Fija workers en (2 * núcleos de CPU + 1) como punto de partida y luego haz benchmarks.
# install the uvicorn worker class
pip install "uvicorn[standard]" gunicorn
# run 4 worker processes managed by gunicorn
gunicorn main:app \
-w 4 \
-k uvicorn.workers.UvicornWorker \
-b 0.0.0.0:8000 \
--timeout 120
# -w workers (commonly 2*CPU+1), -k worker classDespliegue con Docker
Una imagen base de Python ligera mantiene la imagen pequeña. Instala las dependencias antes de copiar el código para aprovechar la caché de capas de Docker. Ejecuta con workers gunicorn+uvicorn dentro del contenedor y expón el puerto 8000 al host o al orquestador.
# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["gunicorn", "main:app", "-w", "4", \
"-k", "uvicorn.workers.UvicornWorker", \
"-b", "0.0.0.0:8000"]
# build & run:
# docker build -t myapi .
# docker run -p 8000:8000 myapiConfiguración de entorno
pydantic-settings (antes pydantic.BaseSettings) carga la configuración desde variables de entorno y archivos .env con validación de tipos. Esto permite que la misma imagen corra en distintos entornos (dev/staging/prod) cambiando solo las variables de entorno.
import os
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
database_url: str = "sqlite:///./app.db"
secret_key: str = "change-me"
debug: bool = False
allowed_origins: list[str] = ["http://localhost:3000"]
class Config:
env_file = ".env"
env_file_encoding = "utf-8"
settings = Settings()
# .env file:
# DATABASE_URL=postgresql://user:pass@db:5432/app
# SECRET_KEY=long-random-string
# DEBUG=falseProxy inverso Nginx
Nginx termina el HTTP(S) y reenvía a Uvicorn en localhost:8000. Fija los headers X-Forwarded-* (y usa --proxy-headers en Uvicorn) para que la app vea la IP y el esquema reales del cliente. Las líneas Upgrade/Connection habilitan el soporte de WebSocket.
# /etc/nginx/conf.d/api.conf
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade \$http_upgrade;
proxy_set_header Connection "upgrade";
}
}Escalado y concurrencia
Escala de dos formas: más procesos worker de Uvicorn por máquina (limitado por CPU) y más máquinas detrás de un balanceador (horizontal). Para apps asíncronas, el event loop maneja muchas peticiones de I/O concurrentes por worker. Añade un endpoint /health para que los orquestadores (k8s, ECS) puedan sondear la vida.
# Workers = process count (vertical scaling); pick ~2*CPU
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
# Inside async app: concurrency is cooperative via the event loop.
# CPU-bound work blocks it — offload to a threadpool or task queue.
# Horizontal scaling: run several containers behind a load balancer.
# Use a shared store (Redis) for session state and rate limits.
# Health check endpoint for the balancer:
@app.get("/health")
def health():
return {"status": "ok"}Temas avanzados
Eventos de lifespan
El context manager de lifespan reemplaza los manejadores obsoletos on_event('startup'/'shutdown'). El código antes del yield corre al arrancar; el código después del yield corre al apagar, incluso si el arranque falla. Úsalo para inicializar conexiones de base de datos, modelos de ML y cachés.
from contextlib import asynccontextmanager
from fastapi import FastAPI
@asynccontextmanager
async def lifespan(app: FastAPI):
# runs at startup
print("starting up")
app.state.cache = {}
yield
# runs at shutdown
print("shutting down")
await app.state.cache.clear()
app = FastAPI(lifespan=lifespan)
# the old @app.on_event("startup") / "shutdown" are deprecated
# in favor of the lifespan handler above.Subaplicaciones (mount)
app.mount() adjunta una subaplicación bajo un prefijo de ruta, útil para APIs versionadas o combinar varias apps. Cada subapp tiene sus propias rutas y esquema OpenAPI; la documentación del padre no incluye las rutas del hijo por defecto.
from fastapi import FastAPI
app = FastAPI()
api_v1 = FastAPI()
api_v2 = FastAPI()
@api_v1.get("/items")
def v1_items():
return {"version": 1}
@api_v2.get("/items")
def v2_items():
return {"version": 2}
app.mount("/v1", api_v1)
app.mount("/v2", api_v2)
# GET /v1/items -> {"version": 1}
# GET /v2/items -> {"version": 2}APIRouter
APIRouter agrupa rutas relacionadas en un módulo con prefijo, tags, dependencias y respuestas compartidos. Inclúyelo vía app.include_router(router) (opcionalmente con su propio prefijo o tags). Es el patrón estándar para estructurar apps no triviales.
from fastapi import APIRouter, Depends
router = APIRouter(
prefix="/items",
tags=["items"],
dependencies=[Depends(verify_token)],
responses={404: {"description": "Not found"}},
)
@router.get("/")
def list_items():
return []
@router.get("/{item_id}")
def get_item(item_id: int):
return {"id": item_id}
# in main.py: app.include_router(router)Archivos estáticos
StaticFiles sirve un directorio de recursos estáticos (imágenes, CSS, JS) bajo un prefijo de URL. Móntalo una vez por directorio. Para frontends SPA, móntalo como ruta final catch-all apuntando a index.html. Los archivos estáticos se saltan el sistema de rutas por velocidad.
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
app = FastAPI()
# serve files from ./static at /static
app.mount("/static", StaticFiles(directory="static"), name="static")
# /static/logo.png -> ./static/logo.png
# /static/css/app.css -> ./static/css/app.cssRespuesta en streaming
StreamingResponse envía una respuesta generada por fragmentos (un generador/iterador) en lugar de construir el body completo en memoria — ideal para exportaciones CSV grandes, streaming de archivos o SSE. Fija media_type adecuadamente para que los clientes manejen el stream correctamente.
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import csv, io
app = FastAPI()
def iter_csv():
output = io.StringIO()
writer = csv.writer(output)
writer.writerow(["id", "name"])
for i in range(1000):
writer.writerow([i, f"name-{i}"])
yield output.getvalue()
output.seek(0)
output.truncate(0)
@app.get("/export.csv")
def export():
return StreamingResponse(
iter_csv(),
media_type="text/csv",
headers={"Content-Disposition": "attachment; filename=export.csv"},
)Clase de ruta personalizada
Heredar de APIRoute te permite envolver cada manejador de ruta con lógica personalizada (logging, trazado, tiempos) sin tocar cada endpoint. Fija app.router.route_class o pasa route_class a APIRouter. El manejador corre por cada petición que coincida.
from fastapi import FastAPI, Request, Response
from fastapi.routing import APIRoute
from typing import Callable
class LoggingRoute(APIRoute):
def get_route_handler(self) -> Callable:
original = super().get_route_handler()
async def handler(request: Request) -> Response:
print(f"-> {request.method} {request.url.path}")
response = await original(request)
print(f"<- {response.status_code}")
return response
return handler
app = FastAPI()
app.router.route_class = LoggingRoute
@app.get("/items")
def items():
return {"items": []}Fragmentos de FastAPI relacionados
Copy-paste ready code for common tasks.
Path Parameters
Capture typed path segments with validation.
Query Parameters
Parse query strings with defaults and validation.
Pydantic Request Body
Validate JSON bodies with Pydantic models.
Dependency Injection
Share logic via Depends and yield-based dependencies.
Response Model
Shape and filter responses with response_model.
JWT Auth
Issue and verify JSON Web Tokens with OAuth2.
Async and Await
Define async handlers and run blocking work in a thread.
Middleware
Add CORS, timing, and custom middleware.
Was this helpful?