Aprende FastAPI: Del Frontend al Backend sin Complicaciones

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 def si tus librerías son asíncronas (httpx async, asyncpg).
• Usa def si 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

1. No crees capas de abstracción antes de necesitarlas. Si no vas a cambiar de DB a corto plazo, no inventes un IRepository.
2. Evita micro‑paquetes para cada función. Agrupa por feature y refactoriza cuando el módulo crezca.
3. 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.
4. Usa Pydantic Settings para configuración validada y .env en desarrollo: Pydantic Settings
5. 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.

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.