Fundamentos de FastAPI

10 ejemplos para empezar con FastAPI: 7 básicos y 3 intermedios.

Prerrequisitos

uv venv && source .venv/bin/activate
uv pip install "fastapi[standard]>=0.115" uvicorn httpx

• FastAPI 0.115+ en Python 3.14 usa Pydantic 2 para la validación.
• Inicia el servidor de desarrollo con fastapi dev main.py.

Ejemplos Básicos

1. API de Hola Mundo

Aplicación mínima con documentación OpenAPI automática.

from fastapi import FastAPI
 
app = FastAPI(title="API de Demostración")
 
@app.get("/")
def read_root() -> dict[str, str]:
    return {"message": "Hola, FastAPI"}

• FastAPI() crea el objeto de aplicación ASGI.
• Las pistas de tipo de retorno aparecen en el esquema generado en /docs.
• Ejecuta con uvicorn main:app --reload o fastapi dev main.py.

Relacionado: Modelos de Solicitud y Respuesta - cuerpos de solicitud tipados

2. Parámetros de Ruta

Captura valores tipados de la ruta de la URL.

from fastapi import FastAPI, HTTPException
 
app = FastAPI()
 
@app.get("/users/{user_id}")
def get_user(user_id: int) -> dict[str, int]:
    if user_id < 1:
        raise HTTPException(status_code=404, detail="Usuario no encontrado")
    return {"user_id": user_id}

• Los nombres de los parámetros de ruta deben coincidir con la plantilla de ruta.
• FastAPI convierte tipos y devuelve 422 ante entradas inválidas.
• Usa HTTPException para respuestas 4xx explícitas.

Relacionado: Middleware y Manejo de Errores - cuerpos de error consistentes

3. Parámetros de Consulta

Filtros opcionales y paginación de la cadena de consulta.

from fastapi import FastAPI, Query
 
app = FastAPI()
 
@app.get("/items")
def list_items(
    skip: int = Query(0, ge=0),
    limit: int = Query(20, ge=1, le=100),
    q: str | None = None,
) -> dict[str, object]:
    return {"skip": skip, "limit": limit, "q": q}

• Query() agrega metadatos de validación más allá de un valor predeterminado simple.
• Los parámetros opcionales usan str | None = None.
• Las restricciones como ge y le aparecen en OpenAPI.

4. Cuerpo de Solicitud JSON

POST JSON validado por modelos Pydantic 2.

from fastapi import FastAPI
from pydantic import BaseModel, Field
 
app = FastAPI()
 
class ItemCreate(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)
 
@app.post("/items", status_code=201)
def create_item(item: ItemCreate) -> ItemCreate:
    return item

• El tipo del cuerpo se infiere de la anotación del parámetro.
• Los fallos de validación devuelven 422 con detail a nivel de campo.
• Usa modelos de entrada y salida separados en los límites de la API.

Relacionado: Modelos de Solicitud y Respuesta - filtrado de response_model

5. Filtrado de Modelo de Respuesta

Oculta campos internos de las respuestas serializadas.

from fastapi import FastAPI
from pydantic import BaseModel
 
app = FastAPI()
 
class UserIn(BaseModel):
    username: str
    password: str
 
class UserOut(BaseModel):
    username: str
 
@app.post("/users", response_model=UserOut)
def create_user(user: UserIn) -> UserIn:
    return user

• response_model controla tanto OpenAPI como la carga útil JSON.
• Nunca devuelvas objetos ORM sin un esquema de respuesta explícito.
• Las contraseñas nunca deben aparecer en los modelos de respuesta.

6. Documentación OpenAPI Automática

Swagger UI interactivo incluido con cada aplicación.

from fastapi import FastAPI
 
app = FastAPI(
    title="API de Inventario",
    version="1.0.0",
    docs_url="/docs",
    redoc_url="/redoc",
)
 
@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}

• Visita /docs para Swagger UI y /redoc para ReDoc.
• Deshabilita la documentación en producción con docs_url=None si la política lo requiere.
• Las cadenas de documentación y las etiquetas de las rutas enriquecen la especificación generada.

7. Códigos de Estado y Encabezados

Establece semántica HTTP en respuestas exitosas.

from fastapi import FastAPI, Response
 
app = FastAPI()
 
@app.post("/notify", status_code=202)
def enqueue(response: Response) -> dict[str, str]:
    response.headers["X-Job-Id"] = "job-42"
    return {"status": "aceptado"}

• Usa 201 para crear, 202 para aceptación asíncrona, 204 para cuerpos vacíos.
• Inyecta Response para establecer encabezados sin cambiar el tipo del cuerpo.
• Documenta códigos de éxito no 200 en OpenAPI con responses={}.

Ejemplos Intermedios

8. Inyección de Dependencias con Depends

Comparte sesiones y configuraciones entre rutas.

from collections.abc import Generator
from fastapi import Depends, FastAPI
 
app = FastAPI()
 
def get_db() -> Generator[dict[str, str], None, None]:
    db = {"connected": "true"}
    yield db
 
@app.get("/items")
def list_items(db: dict[str, str] = Depends(get_db)) -> dict[str, str]:
    return db

• Depends resuelve proveedores una vez por solicitud.
• Usa yield para la configuración y limpieza de conexiones.
• Sobrescribe dependencias en pruebas a través de app.dependency_overrides.

Relacionado: Inyección de Dependencias - subdependencias y ámbitos

9. Módulos APIRouter

Divide APIs grandes en routers de características.

from fastapi import APIRouter, FastAPI
 
users_router = APIRouter(prefix="/users", tags=["users"])
 
@users_router.get("/")
def list_users() -> list[str]:
    return ["ada", "grace"]
 
app = FastAPI()
app.include_router(users_router)

• APIRouter agrupa endpoints con prefijo y etiquetas compartidos.
• Un router por dominio mantiene los archivos mantenibles.
• Monta routers de paquetes de características para importaciones limpias.

Relacionado: Despliegue de FastAPI - diseño de proyectos de producción

10. Manejador de Rutas Asíncrono

E/S no bloqueante con endpoints async def.

import httpx
from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/external")
async def proxy() -> dict[str, str]:
    async with httpx.AsyncClient() as client:
        resp = await client.get("https://httpbin.org/get", timeout=5.0)
    return {"status": str(resp.status_code)}

• Usa async def al esperar E/S HTTP, de base de datos o de caché.
• No llames a bibliotecas bloqueantes dentro de rutas asíncronas sin run_in_threadpool.
• Empareja rutas asíncronas con drivers de base de datos asíncronos como asyncpg.

Relacionado: Rutas Asíncronas y Bases de Datos - sesiones asíncronas de SQLAlchemy

Versiones de la pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.