FastAPI ha ganado popularidad en los últimos años por generar documentación OpenAPI de forma automática, pero exige familiaridad con anotaciones de tipo. Django REST Framework ofrece muchas funcionalidades listas para usar, aunque el tamaño del proyecto crece rápidamente. Flask sigue siendo la opción más directa cuando el objetivo principal es comprender el flujo de una petición sin distracciones.

Ejemplos prácticos con datos concretos

Un caso habitual consiste en exponer un catálogo de productos para una tienda en línea pequeña. El endpoint /productos acepta una petición GET y devuelve una lista de diez elementos con campos id, nombre, precio y stock. Cada precio se almacena como número decimal con dos posiciones para evitar errores de redondeo al realizar cálculos posteriores.

Otro ejemplo frecuente aparece en aplicaciones de registro de asistencia. Aquí se crea un endpoint POST /asistencias que recibe un JSON con el identificador del empleado y la fecha en formato ISO 8601. El servidor valida que la fecha no sea anterior a la actual y devuelve un código 201 junto con el identificador del registro creado.

Un tercer escenario aparece cuando se necesita integrar con un servicio de mensajería. El endpoint /notificaciones envía un mensaje a través de una cola Redis configurada en localhost:6379. El tiempo medio de respuesta medido en pruebas locales oscila entre 45 y 70 milisegundos cuando la cola está vacía.

Pruebas con pytest y requests

1. Escribe una prueba que verifique que el endpoint /productos responde con código 200 y contiene al menos un elemento.
2. Utiliza la fixture client de Flask para simular peticiones sin levantar el servidor completo.
3. Añade una prueba de validación que envíe un JSON incompleto y compruebe que se devuelve el código 400.
4. Ejecuta las pruebas con pytest -q para obtener un resumen rápido del estado del proyecto.

Estas pruebas se integran fácilmente en un flujo de integración continua con GitHub Actions. El archivo de configuración suele ocupar menos de veinte líneas y permite detectar regresiones antes de que lleguen a producción.

Casos de prueba con datos de borde y escenarios de error

Además de las pruebas básicas, conviene incluir casos de borde como el envío de cadenas de texto excesivamente largas, valores negativos en campos que solo aceptan positivos y fechas con formato incorrecto. Estos escenarios ayudan a verificar que las validaciones de Marshmallow funcionan correctamente y que los mensajes de error devueltos son comprensibles para el cliente.

Una métrica útil es el porcentaje de cobertura de código. Herramientas como pytest-cov permiten generar informes que muestran qué líneas de código no han sido ejecutadas durante las pruebas. El objetivo habitual en proyectos medianos es alcanzar al menos un 80 % de cobertura antes de considerar el código listo para producción.

Integración de pruebas de rendimiento básicas

Para complementar las pruebas funcionales, se pueden incorporar pruebas de carga simples con la biblioteca locust. Un script de ejemplo define diez usuarios virtuales que realizan peticiones GET continuas durante sesenta segundos. Los resultados muestran que el percentil 95 de latencia se mantiene por debajo de 120 milisegundos en un entorno local con cuatro núcleos.

Consideraciones de seguridad y rendimiento iniciales

Incluso en una API básica conviene aplicar medidas mínimas de seguridad. El uso de HTTPS mediante un proxy inverso como Nginx o Caddy protege las credenciales durante el transporte. Además, limitar el tamaño del cuerpo de las peticiones con MAX_CONTENT_LENGTH evita ataques de denegación de servicio por carga excesiva de datos.

En cuanto al rendimiento, Flask puede atender varias decenas de peticiones por segundo en un servidor de cuatro núcleos sin optimizaciones adicionales. Cuando el tráfico supera esa cifra, resulta más productivo incorporar Gunicorn con varios workers que reescribir toda la lógica en otro framework. Esta aproximación gradual permite medir el impacto real antes de tomar decisiones de arquitectura más costosas.

• Configura variables de entorno para almacenar claves secretas en lugar de dejarlas en el código fuente.
• Implementa rate limiting básico con flask-limiter para proteger endpoints sensibles.
• Registra logs estructurados en formato JSON para facilitar su análisis posterior con herramientas como ELK.
• Realiza copias de seguridad periódicas de la base de datos aunque el volumen de datos sea todavía reducido.

Estas prácticas no garantizan un sistema invulnerable, pero reducen significativamente la superficie de ataque en etapas tempranas del proyecto.

Integración con bases de datos y ORM

Una vez que la API básica funciona con datos en memoria, el siguiente paso natural es persistir la información en una base de datos. SQLAlchemy es el ORM más utilizado en el ecosistema Flask porque ofrece un equilibrio entre abstracción y control sobre las consultas SQL generadas.

Configuración de la conexión y modelos

La conexión se configura mediante una URI que incluye el dialecto, usuario, contraseña, host y nombre de la base de datos. Para PostgreSQL la cadena típica es postgresql://usuario:contraseña@localhost:5432/nombre_db. Se recomienda utilizar la extensión flask-sqlalchemy que gestiona el ciclo de vida de la sesión y facilita las migraciones con Alembic.

Cada modelo se define como una clase que hereda de db.Model. Los atributos de la clase se corresponden con columnas de la tabla. Por ejemplo, un modelo Producto puede incluir columnas id (Integer, primary key), nombre (String de 120 caracteres), precio (Numeric con precisión 10,2) y stock (Integer con valor por defecto 0).

Consultas y relaciones entre modelos

• Utiliza db.session.query para recuperar registros con filtros, ordenamientos y límites.
• Define relaciones con db.relationship para establecer asociaciones uno a muchos o muchos a muchos.
• Aplica lazy loading con cuidado para evitar consultas innecesarias en cascada.
• Realiza commits explícitos después de operaciones de escritura y maneja excepciones de integridad.

En un proyecto real que gestiona pedidos y clientes, la relación entre Pedido y Cliente se define con una clave foránea. Esto permite realizar consultas como obtener todos los pedidos de un cliente específico en una sola línea de código utilizando la relación definida.

Ejemplos de migraciones con Alembic

Cuando se añade una nueva columna como descripcion a la tabla de productos, se genera una migración con el comando flask db migrate -m "add descripcion column". La revisión resultante contiene operaciones de alter table que pueden revisarse antes de aplicarlas con flask db upgrade. Este flujo mantiene la base de datos sincronizada con el código sin intervención manual directa.

Riesgos adicionales y mitigación en entornos de producción

Además de las medidas básicas, existen riesgos específicos que aparecen cuando la API comienza a recibir tráfico real. Uno de ellos es la exposición accidental de información sensible a través de mensajes de error detallados. Configurar el modo de depuración como False en producción y utilizar manejadores de error personalizados evita que se filtren trazas de pila o nombres de variables internas.

Otro riesgo frecuente es la inyección de SQL cuando se construyen consultas de forma dinámica sin utilizar parámetros. SQLAlchemy previene este problema al utilizar placeholders, pero es necesario revisar cualquier consulta construida manualmente con texto concatenado.

• Implementa autenticación con tokens JWT mediante la extensión flask-jwt-extended.
• Utiliza CORS controlado con flask-cors para permitir únicamente orígenes de confianza.
• Monitorea el consumo de memoria y CPU con herramientas como Prometheus y Grafana.
• Establece tiempos de espera en las conexiones a la base de datos para evitar bloqueos indefinidos.

Documentación automática y pruebas de contrato

Una API sin documentación clara pierde gran parte de su valor para otros equipos. Herramientas como Flask-RESTX o apispec permiten generar especificaciones OpenAPI directamente desde el código de las rutas. En un proyecto con quince endpoints, esta aproximación genera un archivo swagger.json de 120 KB que se actualiza automáticamente cada vez que se modifica una ruta.

Generación de documentación interactiva

Al integrar flask-swagger-ui, los desarrolladores pueden acceder a una interfaz gráfica en /docs donde prueban cada endpoint sin escribir código adicional. Esta práctica reduce el tiempo de onboarding de nuevos integrantes del equipo en un promedio de tres días según experiencias reportadas en empresas medianas de Latinoamérica.

Pruebas de contrato con consumidores

Además de las pruebas unitarias, resulta útil implementar pruebas de contrato que verifiquen que los cambios en la API no rompen los clientes existentes. Bibliotecas como pact-python permiten definir expectativas de respuesta y ejecutarlas en pipelines de CI. Un ejemplo concreto es verificar que el campo precio siempre sea un número decimal y nunca nulo en las respuestas del endpoint /productos.

Despliegue en contenedores y escalabilidad inicial

Una vez que la API funciona correctamente en desarrollo local, el siguiente paso lógico es prepararla para entornos reales mediante contenedores. Docker permite empaquetar la aplicación junto con todas sus dependencias, eliminando problemas de "funciona en mi máquina".

Creación de un Dockerfile optimizado

El archivo Dockerfile comienza con una imagen base ligera como python:3.11-slim. Se copian los archivos de requisitos, se instalan las dependencias y finalmente se copia el código fuente. Utilizar una imagen multi-stage reduce el tamaño final de la imagen a menos de 150 MB, facilitando su distribución en registros como Docker Hub o GitLab Container Registry.

Orquestación con Docker Compose

• Define servicios para la API, la base de datos PostgreSQL y Redis en un único archivo docker-compose.yml.
• Configura volúmenes persistentes para la base de datos y redes aisladas para comunicación interna.
• Utiliza variables de entorno en el archivo compose para inyectar configuraciones sin modificar el código.
• Ejecuta el comando docker-compose up --build para levantar todo el entorno en un solo paso.

Esta configuración permite que un nuevo desarrollador clone el repositorio y tenga la API completa funcionando en menos de dos minutos.

Estrategias de escalado horizontal

Cuando el tráfico aumenta, se puede escalar horizontalmente ejecutando múltiples réplicas del contenedor de la API detrás de un balanceador de carga. Herramientas como Docker Swarm o Kubernetes gestionan la distribución de carga automáticamente. En pruebas controladas, pasar de una a cuatro réplicas incrementó la capacidad de respuesta de 80 a 310 peticiones por segundo manteniendo latencias por debajo de 200 milisegundos.

El tutorial para crear una API básica con framework que se ha presentado aquí busca precisamente eso: ofrecer una base sólida desde la que cualquier persona pueda seguir experimentando sin sentirse abrumada por la complejidad inicial.

Una vez dominados los conceptos de rutas, validación y pruebas, resulta natural avanzar hacia autenticación con JWT, bases de datos relacionales o despliegue en contenedores. La clave está en iterar de forma controlada y medir cada cambio antes de incorporarlo de manera definitiva.

Si quieres conocer otros artículos parecidos a Tutorial para crear una API básica con framework puedes visitar la categoría Tecnologia para Principiantes.