FastAPI explicado para devs que vienen del frontend
Tiempo estimado de lectura: 4 min
- Pydantic trae tipado y validación automática al backend (como Zod/TypeScript).
- Depends ofrece inyección de dependencias limpia y reutilizable (como hooks/contexts).
- /docs genera documentación y clientes a partir de OpenAPI automáticamente.
- Estructura por feature (routers, servicios, schemas) evita sobre‑arquitectura temprana.
- Async vs sync: escoge coherentemente según las librerías de I/O que uses.
Introducción
FastAPI explicado para devs que vienen del frontend: si trabajas con React, Next.js o Angular, lo vas a entender rápido. En pocas líneas: FastAPI trae al backend la ergonomía que ya conoces del frontend —tipado, validación automática y feedback inmediato— pero con la potencia del ecosistema Python para datos y automatización.
Esta guía va al grano: qué partes importan de verdad, cómo estructurar proyectos reales y cómo evitar la sobre‑arquitectura que paraliza más que ayuda.
Resumen rápido (lectores con prisa)
FastAPI es un framework web Python que ofrece validación automática con Pydantic, inyección de dependencias con Depends y documentación OpenAPI automática. Úsalo cuando quieras productividad, tipado y APIs mantenibles sin complejidad innecesaria.
FastAPI explicado para devs que vienen del frontend: los conceptos que importan
Pydantic: tu Zod/TypeScript en el backend
Pydantic define esquemas (models) que validan entrada y salida, generan JSON y alimentan la documentación OpenAPI automática. Piensa en él como Zod del servidor.
from pydantic import BaseModel
class UserCreate(BaseModel):
username: str
email: str
is_admin: bool = False
Si el cliente envía un string donde va un número, FastAPI responde 422. Más seguridad y menos if inútiles. Docs: Docs
Depends: inyección limpia (como hooks)
Depends es el equivalente a usar un hook o un context provider. Te permite inyectar autenticación, sesiones DB o configuración sin repetir código.
from fastapi import Depends
async def get_current_user(token: str):
# decodifica JWT, consulta DB...
return user
@app.get("/me")
async def me(user=Depends(get_current_user)):
return {"username": user.username}
Esto hace tus rutas pequeñas, testables y legibles.
Docs automáticas: /docs es tu Postman actualizado
FastAPI genera Swagger UI y ReDoc desde tus modelos Pydantic. Para frontend, eso significa menos sincronización manual y clientes generados a partir del esquema OpenAPI. FastAPI docs: FastAPI docs
Cómo estructurar un proyecto (sin volverte loco)
Estructura recomendada
La regla: agrupa por dominio/feature, no por tipo de archivo. Es más fácil de escalar y de entender cuando el proyecto crece.
/project
├─ main.py # instancia FastAPI y monta routers
├─ core/
│ ├─ config.py # Pydantic Settings
│ └─ db.py # sesión/engine DB
└─ modules/
└─ users/
├─ router.py # endpoints
├─ schemas.py # Pydantic models
├─ service.py # lógica de negocio
└─ models.py # tablas (SQLModel/SQLAlchemy)
– router.py solo maneja HTTP.
– service.py contiene lógica pura (sin dependencias HTTP).
– schemas.py es tu contrato con el frontend.
Usa SQLModel si quieres combinar Pydantic + SQLAlchemy con menor fricción: SQLModel
Async vs sync: cuándo usar async def
Eres de frontend, ya conoces async/await. En Python:
- Usa
async defsi tus librerías son asíncronas (httpx async, asyncpg). - Usa
defsi dependes de librerías bloqueantes (requests, muchos ORMs syncronous).
FastAPI ejecuta funciones sync en un threadpool, pero mezclar async con llamadas bloqueantes puede congelar la app. Elige coherentemente la capa de I/O. httpx (async) es una buena alternativa a requests.
Cómo no sobre‑arquitectar: reglas prácticas
- No crees capas de abstracción antes de necesitarlas. Si no vas a cambiar de DB a corto plazo, no inventes un
IRepository. - Evita micro‑paquetes para cada función. Agrupa por feature y refactoriza cuando el módulo crezca.
- No conviertas cada operación en un task queue desde el día uno. Añade background jobs (Celery, RQ) cuando el throughput lo exija.
- Usa Pydantic Settings para configuración validada y
.enven desarrollo: Pydantic Settings - Empieza con tests simples en service.py: funciones puras son triviales de testear con
pytest.
Deploy mínimo reproducible
Dockerfile simple:
FROM python:3.11-slim
WORKDIR /app
COPY pyproject.toml poetry.lock ./
RUN pip install poetry && poetry install --no-root --only main
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
Usa Uvicorn para prod. Plataformas como Railway, Render o Fly.io son opciones rápidas con SSL automático.
Pequeño checklist antes de merge
- Modelos Pydantic definidos para input/output.
- Dependencias reutilizables con
Depends. - Rutas cortas: lógica en service.py, no en router.
- Logs estructurados y errores manejados correctamente.
- Tests para la lógica (no solo integración).
Cierre
FastAPI te permite pasar de frontend a backend sin perder la mentalidad de DX y tipado que ya dominas. Aprende Pydantic, usa Depends con juicio y estructura por feature. No abuses de patrones hasta que el problema los justifique. En 10 minutos tendrás un endpoint funcional; en unas pocas iteraciones, una API mantenible y profesional.
Si te interesa explorar integraciones, automatizaciones y flujos avanzados relacionados con APIs y agentes, visita Dominicode Labs para recursos y experimentos prácticos.
FAQ
- ¿Por qué usar Pydantic en FastAPI?
- ¿Cuándo debo usar Depends?
- ¿Qué diferencia hay entre async y sync en FastAPI?
- ¿Debo empezar con SQLModel o SQLAlchemy?
- ¿Cómo evito sobre‑arquitectar mi backend?
- ¿Qué pongo en los tests iniciales?
¿Por qué usar Pydantic en FastAPI?
Pydantic valida entrada y salida, genera JSON y alimenta la documentación OpenAPI. Reduce checks manuales y errores de tipo, mejorando la seguridad y la ergonomía del desarrollo.
¿Cuándo debo usar Depends?
Usa Depends para autenticación, sesiones DB, configuración u otras dependencias reutilizables. Mantiene las rutas limpias y facilita testing.
¿Qué diferencia hay entre async y sync en FastAPI?
Usa async def si tus librerías de I/O son asíncronas; usa def si son bloqueantes. Mezclar ambos sin cuidado puede bloquear la app.
¿Debo empezar con SQLModel o SQLAlchemy?
Si quieres integrar Pydantic y ORM con menor fricción, SQLModel es una opción práctica. Si necesitas control avanzado, SQLAlchemy puro puede ser más adecuado.
¿Cómo evito sobre‑arquitectar mi backend?
No crees abstracciones ni micro‑paquetes antes de necesitarlos. Agrupa por feature y añade capas solo cuando el problema lo justifique.
¿Qué pongo en los tests iniciales?
Empieza por tests unitarios en service.py (funciones puras) y algunos tests de integración básicos para rutas críticas.
