FastAPI es un framework moderno para crear APIs con Python. Destaca por su sintaxis clara, validación automática de datos, documentación interactiva y excelente compatibilidad con programación asíncrona. Es especialmente útil para servicios web, aplicaciones móviles, microservicios, modelos de inteligencia artificial y sistemas que necesitan intercambiar datos mediante JSON.
Qué hace diferente a FastAPI
FastAPI utiliza anotaciones de tipo de Python para describir los datos que recibe y devuelve cada endpoint. A partir de esas anotaciones genera validación, documentación OpenAPI y mensajes de error detallados. Por eso conviene comprender primero los type hints en Python. La guía oficial de FastAPI muestra cómo construir una API desde los ejemplos más sencillos hasta autenticación y bases de datos.
Instalación y primer endpoint
Crea un entorno virtual e instala FastAPI junto con un servidor ASGI como Uvicorn:
python -m venv .venv
# activa el entorno y ejecuta:
python -m pip install fastapi uvicornDespués crea un archivo main.py:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def inicio():
return {"mensaje": "Hola desde FastAPI"}Ejecuta uvicorn main:app --reload. La API estará disponible en http://127.0.0.1:8000, mientras que la documentación interactiva aparecerá en /docs y /redoc. El modo --reload es útil durante el desarrollo, pero no debe utilizarse como configuración de producción.
Parámetros de ruta y consulta
Los parámetros de ruta forman parte de la URL. Los parámetros de consulta aparecen después del signo de interrogación. FastAPI convierte y valida los valores automáticamente.
@app.get("/productos/{producto_id}")
def obtener_producto(producto_id: int, moneda: str = "USD"):
return {
"id": producto_id,
"moneda": moneda
}Si el usuario envía texto donde se esperaba un entero, FastAPI responde con un error estructurado. Esta validación temprana reduce errores dentro de la lógica de negocio.
Modelos con Pydantic
Para recibir JSON se crean modelos basados en Pydantic. Estos modelos definen campos obligatorios, valores predeterminados y reglas de validación.
from pydantic import BaseModel, Field
class Producto(BaseModel):
nombre: str = Field(min_length=2, max_length=100)
precio: float = Field(gt=0)
disponible: bool = True
@app.post("/productos")
def crear_producto(producto: Producto):
return {"producto": producto}La documentación oficial de Pydantic explica validadores, serialización, modelos anidados y configuraciones avanzadas.
Funciones normales y funciones async
FastAPI acepta endpoints creados con def y con async def. Usa async def cuando la operación espera recursos externos compatibles con asincronía, como una base de datos asíncrona o una solicitud HTTP. No conviertas todo a async de forma automática: el código bloqueante dentro de una función asíncrona puede perjudicar el rendimiento.
Para reforzar la estructura de endpoints, consulta la guía de funciones en Python. También es frecuente crear dependencias reutilizables con funciones que validan usuarios, abren sesiones de base de datos o comprueban permisos.
Manejo de errores y códigos HTTP
Una API debe responder con códigos correctos. FastAPI incluye HTTPException para devolver errores controlados.
from fastapi import HTTPException
@app.get("/usuarios/{usuario_id}")
def obtener_usuario(usuario_id: int):
if usuario_id != 1:
raise HTTPException(
status_code=404,
detail="Usuario no encontrado"
)
return {"id": 1, "nombre": "Ana"}Evita devolver siempre el código 200. Utiliza 201 para creación, 204 cuando no hay contenido, 400 para datos inválidos, 401 para autenticación, 403 para permisos y 404 cuando el recurso no existe.
Autenticación y variables de entorno
FastAPI soporta OAuth2, tokens Bearer, JWT y esquemas personalizados. Nunca guardes claves secretas o contraseñas dentro del repositorio. La guía para leer variables de entorno de forma segura muestra cómo cargar configuraciones sin exponerlas. En sistemas reales también deben aplicarse expiración de tokens, hash de contraseñas y permisos por usuario.
Base de datos y organización del proyecto
Un proyecto pequeño puede comenzar en un solo archivo, pero debe dividirse cuando crece. Una estructura común separa rutas, modelos, esquemas, servicios, dependencias y configuración. Para bases de datos se pueden usar SQLAlchemy, SQLModel u otras bibliotecas. Mantén la lógica de negocio fuera de los endpoints para facilitar pruebas y mantenimiento.
FastAPI frente a Django
FastAPI es ideal para APIs, servicios asíncronos y documentación automática. Django ofrece un ecosistema más completo para sitios tradicionales, formularios, panel administrativo y autenticación integrada. El artículo sobre Django para aplicaciones web ayuda a comparar ambos enfoques. No existe un ganador universal: la elección depende del producto.
Pruebas, rendimiento y despliegue
Las APIs deben probar rutas exitosas, validaciones y errores. FastAPI se integra bien con pytest y clientes de prueba. Antes de optimizar, mide el comportamiento real; la guía de cProfile para encontrar cuellos de botella ayuda a evitar optimizaciones basadas en suposiciones.
En producción utiliza un proceso administrado, configuración segura, HTTPS, logs, límites de solicitudes y monitoreo. Desactiva el modo de recarga, configura correctamente los workers y revisa si las dependencias son realmente asíncronas. Con estas prácticas, FastAPI permite construir servicios claros, rápidos y fáciles de documentar.
Dependencias reutilizables
El sistema de dependencias de FastAPI permite ejecutar lógica común antes de un endpoint. Una dependencia puede leer un token, validar un encabezado, obtener una conexión de base de datos o comprobar permisos. Se declara con Depends, y FastAPI resuelve automáticamente sus parámetros. Esta técnica evita copiar la misma validación en muchas rutas y facilita sustituir componentes durante las pruebas.
from fastapi import Depends, Header, HTTPException
def validar_token(x_token: str = Header()):
if x_token != "token-demo":
raise HTTPException(status_code=401, detail="Token inválido")
return x_token
@app.get("/privado")
def privado(token: str = Depends(validar_token)):
return {"acceso": True}En producción, el valor no debe escribirse directamente en el archivo. Debe provenir de una configuración segura y utilizar un mecanismo de autenticación apropiado.
Documentar respuestas y modelos
Una API clara no solo recibe datos bien definidos: también declara lo que devuelve. El parámetro response_model filtra campos, documenta la respuesta y reduce el riesgo de exponer información sensible. Por ejemplo, un modelo público de usuario no debería incluir el hash de la contraseña. Añade descripciones, ejemplos y códigos de respuesta relevantes para que otros equipos puedan integrar el servicio sin depender de explicaciones informales.
