Cheatsheet de FastAPI: Rutas, Parámetros, Pydantic, Dependencias y Errores

Lo esencial de FastAPI en una página: rutas para cada método HTTP, parámetros tipados con validación, modelos Pydantic de petición y respuesta, dependencias, routers y manejo de errores.

🧪

Ejecuta y Edita este Código en Vivo Sin instalaciones locales. Soporta Python 3, JS y SQL.

▶ Probar en Playground →

1. Tu primera app y las rutas básicas

Instala con pip install fastapi uvicorn, ejecuta con uvicorn main:app --reload y documenta todo gratis en /docs. Los decoradores de método HTTP reflejan los verbos REST.

CODE SNIPPET

from fastapi import FastAPI, status

app = FastAPI(title="Shop API", version="1.0.0")

@app.get("/health")
def health():
    return {"status": "ok"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

@app.post("/items", status_code=status.HTTP_201_CREATED)
def create_item(item: dict):
    return item

@app.put("/items/{item_id}")   # reemplazo completo
@app.patch("/items/{item_id}") # actualización parcial
@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_item(item_id: int):
    return None

2. Parámetros y validación

Los type hints son validación: FastAPI convierte y comprueba los datos entrantes, y devuelve un 422 con detalles cuando algo falla. Query, Path, Header y Body añaden valores por defecto y restricciones.

Patrón	Qué declara
`def f(q: str \| None = None)`	Parámetro de consulta opcional
`def f(q: str = Query("fixed", min_length=3, max_length=50))`	Consulta con valores por defecto y límites de longitud
`def f(item_id: int = Path(ge=1))`	Parámetro de ruta que debe ser ≥ 1
`def f(tags: list[str] = Query([]))`	Parámetro repetido: ?tags=a&tags=b
`def f(x_token: str = Header(...))`	Cabecera obligatoria
`def f(session: str = Cookie(None))`	Valor de cookie
`async def f(file: UploadFile = File(...))`	Archivo subido (en streaming, sin cargarlo entero)
`def f(payload: dict = Body(...))`	Cuerpo JSON crudo sin modelo

3. Modelos Pydantic: peticiones y respuestas

Los modelos definen el contrato en ambas direcciones. response_model filtra lo que sale de la API, para que los campos internos (hashes, costes) nunca se filtren por accidente.

CODE SNIPPET

from pydantic import BaseModel, Field

class ItemIn(BaseModel):
    name: str = Field(min_length=1, max_length=80)
    price: float = Field(gt=0)
    tags: list[str] = []

class ItemOut(BaseModel):
    id: int
    name: str
    price: float
    tags: list[str]

@app.post("/items", response_model=ItemOut, status_code=201)
def create_item(item: ItemIn):
    saved = save_to_db(item)   # devuelve dict/objeto con campos extra
    return saved               # solo se exponen los campos de ItemOut

4. Dependencias, routers y errores

Las dependencias inyectan lógica compartida (autenticación, sesiones de base de datos) en cualquier ruta. Los routers dividen las APIs grandes por dominio, y HTTPException produce respuestas de error limpias y consistentes.

CODE SNIPPET

from fastapi import Depends, HTTPException, APIRouter

def get_db():
    db = SessionLocal()
    try:
        yield db               # valor inyectado en la ruta
    finally:
        db.close()             # limpieza garantizada

router = APIRouter(prefix="/items", tags=["items"])

@router.get("/{item_id}")
def read_item(item_id: int, db=Depends(get_db)):
    item = db.get(Item, item_id)
    if item is None:
        raise HTTPException(status_code=404, detail="Item not found")
    return item

app.include_router(router)