4.2API web con Flask y FastAPI
Lo esencial en 30 segundos
- API = contrato JSON : recursos (
GET /articles,POST /articles) y estados que dicen la verdad (200 leído, 201 creado, 400 inválido, 404 no encontrado). - Flask = libertad minimalista (servicios pequeños, aprender) ; FastAPI = moderno : type hints → validación automática + documentación interactiva
/docs, async nativo. - Reflejo de Nabil : diseñar recursos y estados ANTES del código, validar toda entrada con Pydantic, probar con TestClient.
Mini-caso hilado — Nabil sirve sus ventas en JSON
El back-office Django de Nabil (4.1) es muy útil, pero un colega quiere las cifras de ventas en un cuadro de mando separado : necesita JSON, no páginas HTML. Nabil construye una pequeña API FastAPI en Argel : GET /ventes para leer, POST /ventes (201 si creado, 400 si inválido) para añadir, con validación Pydantic y documentación interactiva en /docs. El colega explora la API solo, sin llamar a Nabil. Segundo hito del hilo : los mismos datos, servidos a todos los clientes.
Continuación del caso 4.1 — Nabil separa sus datos de su visualización.
1. API REST : recursos, JSON y estados
Una API REST expone datos en JSON mediante URL y métodos HTTP : GET /ventes lee, POST /ventes crea, y el estado HTTP dice el resultado — 200 leído, 201 creado, 400 entrada inválida, 404 no encontrado. El JSON (claves/valores, listas) corresponde exactamente a los dict y list de Python : es el formato universal. Nabil diseña primero sus recursos y sus estados — el contrato — antes de escribir la menor línea.
2. Flask minimalista, FastAPI moderno
Flask es un micro-framework : una ruta = una URL hacia una función, libertad total, ideal para aprender y para servicios pequeños. FastAPI es su sucesor moderno : los type hints (titre: str) alimentan a Pydantic, que valida cada entrada automáticamente, la documentación OpenAPI se genera sola (página interactiva /docs) y el async nativo (async/await) procesa las peticiones simultáneas sin bloquear. Nabil elige FastAPI para su API de ventas : validación + documentación viva sin esfuerzo.
Y lo fiabilizamos : probar cada ruta con pytest + TestClient (POST válido → 201, POST inválido → 400) y documentar vía /docs en lugar de un documento Word que caduca. Una API probada y autodocumentada es un contrato que los colegas usan sin molestaros.
🔎 Ejemplo concreto — 🔎 Ejemplo concreto — La API de ventas de Nabil
Los gestos de Nabil con las API reales de FastAPI :
class Vente(BaseModel): ville: str; montant: float # validado auto
@app.get("/ventes") → lista en JSON (200)
@app.post("/ventes", status_code=201) → crea (201) o 400 si inválida
uvicorn main:app --reload + doc en /docsLectura : modelo validado, dos rutas, estados explícitos.
Lección : los hints dan validación + documentación.
Vocabulario de la sección
- API REST
- Datos expuestos en JSON mediante URL y métodos HTTP (GET leer, POST crear), con estados que dicen el resultado.
Ejemplo sencillo: La API de Nabil : GET /ventes lee, POST /ventes crea (201).
Lo que no es: páginas HTML reservadas a una sola visualización.
Reflejo: diseñar recursos + estados antes del código.
- Flask
- Micro-framework Python minimalista : una ruta = una URL hacia una función ; libertad total, ideal para aprender y servicios pequeños.
Ejemplo sencillo: Nabil maqueta allí su primer prototipo de API en pocas líneas.
Lo que no es: un framework completo que impone admin y ORM.
Reflejo: ¿servicio pequeño a medida? Flask basta.
- FastAPI + Pydantic
- Framework API moderno : los type hints alimentan a Pydantic, que valida las entradas, genera la documentación OpenAPI y soporta async.
Ejemplo sencillo: La Venta de Nabil se valida (importe numérico requerido) sin código de control.
Lo que no es: entradas aceptadas sin verificación.
Reflejo: tipar cada modelo de entrada, probar el 400.
- Estados HTTP
- Códigos de resultado : 200 leído, 201 creado, 400 entrada inválida, 404 no encontrado — el contrato que el cliente lee primero.
Ejemplo sencillo: El POST de Nabil responde 201 si creado, 400 si falta el importe.
Lo que no es: un 200 devuelto para todo, éxitos como errores.
Reflejo: cada ruta : ¿qué estado para qué caso?
En la práctica — En práctica — Servir una API FastAPI
- Instalad fastapi y uvicorn en un venv y luego declarad un modelo Pydantic (p. ej. Vente : ville str, montant float).
- Añadid GET /ventes (leer, 200) y POST /ventes (crear, status_code=201) sobre una lista en memoria.
- Lanzad con « uvicorn main:app --reload » y explorad la documentación interactiva en /docs : probad desde el navegador.
- Escribid 2 pruebas (pytest + TestClient) : POST válido → 201, POST inválido → 400 ; corregid hasta el verde.
Guion listo para decir — presentar su API (30 s)
« Soy Nabil : nuestras ventas se sirven en JSON — GET para leer, POST en 201 para crear, 400 si la entrada es inválida. Pydantic lo valida todo, la documentación en /docs está actualizada de oficio y las pruebas blindan el contrato. »
Para decir en demo ; mostrad /docs en directo.
Modelo copiar-pegar — API FastAPI (código probado)
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Vente(BaseModel):
ville: str
montant: float
VENTES: list[Vente] = []
@app.get("/ventes")
def lister():
return VENTES
@app.post("/ventes", status_code=201)
def creer(vente: Vente):
VENTES.append(vente)
return vente
# Lanzar : uvicorn main:app --reload
# Documentación interactiva : /docs
# Prueba :
# from fastapi.testclient import TestClient
# client = TestClient(app)
# assert client.post("/ventes", json={"ville": "Alger", "montant": 1200.5}).status_code == 201
# assert client.post("/ventes", json={"ville": "Alger"}).status_code == 422
Prototipo rápido
Flask en pocas líneas : una ruta, JSON, y vuestra idea es demostrable esta noche.
API de equipo
Como Nabil : FastAPI + Pydantic en todas partes, /docs como documentación oficial, TestClient por rutina.
Tráfico intenso
Pasad las vistas pesadas a async (async def) : las esperas de red ya no acumulan las peticiones.
Datos Django
Conservad vuestros modelos Django (4.1) y exponedlos en JSON : mismos datos, nuevo contrato, cero reescritura.
✓ Buenas prácticas
- Diseñar el contrato (recursos + estados) antes del código.
- Validar toda entrada con Pydantic.
- Probar con TestClient y documentar vía /docs.
✗ Errores frecuentes
- Devolver 200 para todo, éxitos como errores.
- Aceptar entradas no validadas.
- Mantener una documentación separada que caduca.
Puntos clave
- API REST = JSON vía URL + MÉTODOS HTTP ; ESTADOS que dicen la verdad (200/201/400/404).
- FLASK minimalista (libertad, servicios pequeños) ; FASTAPI moderno (validación automática, /docs, async).
- PYDANTIC valida desde los type hints ; TESTCLIENT blinda el contrato.
- Mismos datos, varios clientes : separar la exposición de la visualización.
Reto 48h — aplica mañana
Exponed vuestros propios datos : GET + POST con modelo Pydantic, 201/400 correctos, /docs explorada y 2 pruebas en verde.
- Puedo citar recursos, JSON, estados 200/201/400/404.
- Sé explicar la validación Pydantic y /docs.
- Tengo 1 API probada que sirve mis datos.
Preguntas frecuentes
¿Por qué el JSON está en todas partes en las API?
Porque es un formato de texto ligero en claves/valores y listas que corresponde exactamente a los dict y list de Python : legible por el humano, manipulable en una línea de código, comprendido por todos los lenguajes. El cliente recibe JSON, lo convierte en objetos nativos y trabaja — sin controlador ni formato propietario.
¿Para qué sirve el async (async/await) en FastAPI?
Para procesar muchas peticiones simultáneas sin bloquear : mientras una petición espera a la base o a la red, el servidor procesa las demás en lugar de esperar. Para una API que lee datos o llama a servicios, el async aumenta claramente el rendimiento con el mismo servidor — sin cambiar la lógica.
¿Qué expone una API REST a sus clientes?