Creación de APIs REST
Endpoints JSON con validación y OpenAPI.
Receta
Tarjeta de receta de referencia rápida, lista para copiar y pegar.
from flask import Flask, request
from pydantic import BaseModel, ValidationError
class Item(BaseModel):
name: str
@app.post("/items")
def create():
try:
item = Item.model_validate(request.get_json())
except ValidationError as e:
return {"errors": e.errors()}, 422
return item.model_dump(), 201Cuándo usar esto:
- CRUD JSON
- Validación con Pydantic
- OpenAPI a través de flask-smorest
Ejemplo de trabajo
from flask.views import MethodView
class ItemsView(MethodView):
def get(self):
return []
def post(self):
return {}, 201Lo que esto demuestra:
- Clases
MethodView - Métodos de verbo HTTP
- REST basado en clases
Análisis detallado
Cómo funciona
- Validar en el límite con Pydantic 2.
flask-smorestgenera OpenAPI 3.- Devolver JSON de error coherente.
Errores comunes
- Validación de límites omitida: Datos inválidos llegan a las capas de persistencia. Solución: Validar con Pydantic o formularios del framework en el borde.
- Fugas de trazas de pila: Los clientes ven errores internos. Solución: Mapear excepciones a respuestas HTTP estables.
- Bloqueo de bucles de eventos asíncronos: Los trabajadores se bloquean bajo carga concurrente. Solución: Usar controladores asíncronos o envoltorios de pool de hilos.
- Secretos en control de código fuente: Las credenciales se filtran a través del historial de git. Solución: Cargar secretos desde el entorno o una bóveda en tiempo de ejecución.
- Falta de observabilidad: Los incidentes son difíciles de depurar. Solución: Añadir registros estructurados, métricas e IDs de solicitud.
Alternativas
| Alternativa | Usar cuándo | No usar cuándo |
|---|---|---|
| Framework alternativo en este cookbook | Estándar del equipo o monolito existente | API nueva con restricciones diferentes |
| BaaS gestionado | Solo MVP de CRUD | Autenticación personalizada, flujos de trabajo o necesidades de cumplimiento |
| gRPC | RPC interno de alto rendimiento | Clientes HTTP públicos y acceso al navegador |
Preguntas frecuentes
¿Cuándo debo adoptar las APIs REST de Flask?
Úsalo cuando los patrones y las compensaciones de esta página coincidan con tu API o límite de datos.
¿Cuál es el principal error de producción con las APIs REST de Flask?
Omitir la validación, los tiempos de espera o los contratos de error explícitos en el borde HTTP.
¿Cómo pruebo las APIs REST de Flask?
Usa el cliente de prueba del framework, anula las dependencias y verifica el estado más la forma del JSON.
¿Flask REST APIs funciona con Python 3.14?
Sí, los ejemplos se dirigen a Python 3.14 con versiones de framework fijadas del pie de página de la pila.
¿Cómo se relaciona Flask REST APIs con Pydantic 2?
Validar y serializar en los límites; mantener los servicios funcionando con objetos de dominio tipados.
¿Síncrono o asíncrono?
Prefiere rutas asíncronas cuando las E/S dominan; mantén el trabajo de CPU pequeño o descárgalo a los trabajadores.
¿Dónde debe residir la lógica de negocio?
Controladores delgados; los servicios poseen las reglas; los repositorios poseen las consultas.
¿Cómo documento las APIs?
Publica documentación OpenAPI o de esquema que coincida con los modelos de respuesta en el código.
¿Cómo manejo el versionado?
Versionado explícito de URL o encabezado con ventanas de deprecación; evita roturas silenciosas.
¿Qué debo leer a continuación?
Sigue los enlaces Relacionados para la siguiente capa de profundidad en esta sección.
¿Cómo me mantengo seguro?
Autentica a los llamadores, autoriza por recurso, limita la tasa y nunca registres secretos.
¿Primer paso para el rendimiento?
Mide la latencia de la base de datos y la de los sistemas ascendentes antes de cambiar de framework.
Relacionado
- Fundamentos de Flask - Rutas y solicitudes
- Fábricas de aplicaciones y Blueprints - Estructura
- Creación de APIs REST - Endpoints JSON
- Despliegue de Flask - WSGI en producción
Versiones de la pila: Esta página se escribió 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+.