Skip to content

FastAPI Hoja de referencia

Framework web de Python moderno y rápido para construir APIs.

01

Primeros pasos

Primera API

FastAPI se construye sobre Starlette y Pydantic. uvicorn es el servidor ASGI. --reload habilita la autorrecarga durante el desarrollo.

fastapi
# 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 --reload

Ejecutar 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.

fastapi
# 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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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")
02

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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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} pattern

Pará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.

fastapi
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"}
03

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.

fastapi
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=10

Pará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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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 null

Pará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.

fastapi
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 required
04

Cuerpo 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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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 result
05

Modelo 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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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=True

Respuesta 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.

fastapi
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.

fastapi
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)
06

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.

fastapi
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=secret

UploadFile 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.

fastapi
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.

fastapi
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/uploads

Archivo 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.

fastapi
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.

fastapi
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.

fastapi
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)}
07

Headers y cookies

Parámetros de header

Header() declara un parámetro leído de los headers de la petición. FastAPI convierte los guiones bajos de los nombres de Python en guiones (x_token -> X-Token). Fija convert_underscores=False para desactivar este comportamiento.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

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

# Header names are case-insensitive; an underscore in the
# parameter (x_token) is converted to a hyphen (X-Token) automatically.
@app.get("/secure")
def secure(x_token: str = Header()):
    return {"x-token": x_token}

Parámetros de cookie

Cookie() lee un valor del header Cookie de la petición. Como los parámetros de query, las cookies sin valor por defecto son obligatorias, y puedes aplicar validación (min_length, max_length, etc.).

fastapi
from fastapi import FastAPI, Cookie

app = FastAPI()

@app.get("/session")
def read_session(session_id: str | None = Cookie(default=None)):
    if session_id:
        return {"session_id": session_id}
    return {"message": "no session"}

# Reads the 'session_id' cookie from the Cookie header.

Fijar cookie en la respuesta

Inyecta un Response y llama a set_cookie() para escribir cookies en la respuesta saliente. Usa httponly=True (bloquea el acceso desde JS), secure=True (solo HTTPS) y samesite='lax'/'strict' para mitigar CSRF. El body de la respuesta se devuelve con normalidad.

fastapi
from fastapi import FastAPI, Response

app = FastAPI()

@app.post("/login")
def login(response: Response):
    response.set_cookie(
        key="session_id",
        value="abc123",
        httponly=True,
        max_age=1800,
        secure=True,
        samesite="lax",
    )
    return {"message": "logged in"}

@app.post("/logout")
def logout(response: Response):
    response.delete_cookie("session_id")
    return {"message": "logged out"}

Headers de respuesta personalizados

Fija headers en un Response inyectado para añadirlos a la respuesta JSON que construya FastAPI, o pasa headers= al devolver directamente una subclase de Response. Los headers personalizados se usan a menudo para información de rate limit y tiempos de proceso.

fastapi
from fastapi import FastAPI, Response
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/data")
def get_data(response: Response):
    response.headers["X-Process-Time"] = "0.05"
    response.headers["X-Custom-Header"] = "hello"
    return {"data": 1}

@app.get("/direct")
def direct():
    return JSONResponse(
        content={"data": 1},
        headers={"X-Source": "direct"},
    )

Headers estándar

Headers comunes como Host, Accept, Authorization, If-None-Match son accesibles vía Header(). Para Authorization, prefiere las utilidades de seguridad integradas (HTTPBearer, OAuth2), que manejan el parseo y la documentación OpenAPI por ti.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/info")
def info(
    host: str | None = Header(default=None),
    accept: str | None = Header(default=None),
    authorization: str | None = Header(default=None),
    if_none_match: str | None = Header(default=None),
):
    return {"host": host, "accept": accept}

Valores de header duplicados

Declarar un tipo de lista para un parámetro Header recoge cada valor de header repetido en una lista. Es útil para headers como Set-Cookie (respuesta) o cualquier header personalizado que pueda aparecer varias veces.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/multi")
def multi(x_token: list[str] | None = Header(default=None)):
    return {"x_token": x_token}

# Request with:
#   X-Token: a
#   X-Token: b
# -> {"x_token": ["a", "b"]}
08

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.

fastapi
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 commons

Dependencias 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.

fastapi
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 type

Dependencias 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).

fastapi
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 user

Dependencias 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.

fastapi
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.

fastapi
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 checked

Dependencias 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.

fastapi
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"}
09

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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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 user

Flujo 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.

fastapi
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.
10

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.

fastapi
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 response

Middleware 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.

fastapi
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 headers

BaseHTTPMiddleware

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.

fastapi
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 configurable

Redirecció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.

fastapi
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.

fastapi
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 response

Orden 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.

fastapi
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 -> CORS
11

CORS

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 ['*'].

fastapi
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.

fastapi
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.

fastapi
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 requests

Verbos 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.

fastapi
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 headers

Peticiones 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.

fastapi
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).

fastapi
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=["*"],
)
12

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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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.

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_ERROR

Manejador 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.

fastapi
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")
13

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.

fastapi
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).

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
# 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.

fastapi
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}
14

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.

fastapi
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.

fastapi
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 available

Cerrar 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).

fastapi
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.

fastapi
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.

fastapi
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:
        pass

WebSocket 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.

fastapi
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)
15

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.

fastapi
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.

fastapi
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 afterward

Definició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.

fastapi
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.

fastapi
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 item

Consultar 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.

fastapi
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 item

Actualizar 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.

fastapi
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()
16

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.

fastapi
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.

fastapi
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.name

Crear 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.

fastapi
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).

fastapi
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 item

Actualizar 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.

fastapi
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.

fastapi
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.
17

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.

fastapi
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.

fastapi
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 == 422

Fixture 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.

fastapi
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 -v

Sobrescribir 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.

fastapi
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.

fastapi
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.

fastapi
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 connection
18

Documentació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.

fastapi
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/docs

ReDoc

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).

fastapi
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.

fastapi
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.

fastapi
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 item

Ejemplos 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.

fastapi
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 item

Esquema 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.

fastapi
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_openapi
19

Despliegue (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.

fastapi
# 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.

fastapi
# 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 class

Despliegue 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.

fastapi
# 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 myapi

Configuració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.

fastapi
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=false

Proxy 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.

fastapi
# /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.

fastapi
# 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"}
20

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.

fastapi
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.

fastapi
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.

fastapi
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.

fastapi
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.css

Respuesta 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.

fastapi
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.

fastapi
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": []}

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.