FastAPI: Framework web moderno de alto rendimiento para Python

Construya APIs veloces con documentación automática y seguridad de tipos

Índice

FastAPI ha surgido como una de las marcos más emocionantes de Python para construir APIs, combinando características modernas de Python con un rendimiento excepcional y una experiencia del desarrollador.

Ya sea que estés construyendo microservicios, funciones serverless o aplicaciones web complejas, FastAPI proporciona las herramientas que necesitas para APIs listas para producción.

python y fastapi castillo

¿Qué es FastAPI?

FastAPI es un marco moderno y de alto rendimiento para construir APIs con Python 3.8+ basado en las sugerencias de tipo estándar de Python. Creado por Sebastián Ramírez, está diseñado para ser fácil de usar, rápido de codificar y listo para producción desde el principio.

El marco se apoya en dos bibliotecas poderosas:

  • Starlette para enrutamiento web y capacidades asincrónicas
  • Pydantic para validación de datos usando sugerencias de tipo de Python

Esta combinación entrega un rendimiento comparable al de Node.js y Go, manteniendo la simplicidad y legibilidad de Python. FastAPI ha ganado rápidamente popularidad, con miles de estrellas en GitHub y adopción por parte de empresas importantes en todo el mundo.

Características clave que diferencian a FastAPI

1. Documentación de API automática

Una de las características más queridas de FastAPI es la documentación de API automática e interactiva. Basada en el estándar OpenAPI (anteriormente Swagger), FastAPI genera dos interfaces de documentación:

  • Swagger UI en /docs - Documentación interactiva donde puedes probar directamente los puntos finales de la API en el navegador
  • ReDoc en /redoc - Alternativa de documentación con un diseño limpio de tres paneles

La documentación se genera automáticamente desde las sugerencias de tipo y docstrings de tu código, sin necesidad de configuración adicional. Esto significa que tu documentación siempre está actualizada con tu código.

2. Sugerencias de tipo y validación

FastAPI aprovecha las sugerencias de tipo de Python no solo para la documentación, sino también para la validación y serialización en tiempo de ejecución. Cuando defines un parámetro de un punto final como int, FastAPI automáticamente:

  • Valida que la solicitud contenga un entero
  • Convierte el valor de cadena a entero
  • Devuelve mensajes de error claros si falla la validación
  • Documenta el tipo de parámetro en la documentación de la API
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    username: str
    email: str
    age: int

@app.post("/users/")
async def create_user(user: User):
    return {"message": f"Usuario {user.username} creado exitosamente"}

Este enfoque detecta errores temprano, reduce el código repetitivo y hace que tu API sea auto-documentada.

3. Soporte asincrónico

FastAPI está construido sobre ASGI (Asynchronous Server Gateway Interface) en lugar de WSGI, lo que le da soporte nativo a async/await. Esto es crucial para aplicaciones de alto rendimiento que realizan muchas llamadas I/O (consultas a bases de datos, solicitudes a API, operaciones de archivos).

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    # Las operaciones asincrónicas no bloquean otras solicitudes
    data = await fetch_from_database(item_id)
    return data

El soporte asincrónico significa que FastAPI puede manejar miles de conexiones concurrentes de manera eficiente, lo que lo hace ideal para aplicaciones en la nube modernas y arquitecturas de microservicios.

4. Rendimiento

FastAPI es uno de los marcos más rápidos de Python disponibles, con un rendimiento comparable al de los marcos de Node.js y Go. Los benchmarks independientes muestran consistentemente que FastAPI supera a los marcos tradicionales como Flask y Django con margen significativo, especialmente para cargas de trabajo acotadas por I/O.

La velocidad proviene de:

  • La validación a nivel C de Pydantic
  • La implementación eficiente asincrónica de Starlette
  • El mínimo sobrecarga en el propio marco

Comenzando con FastAPI

Instalar FastAPI es sencillo. Cuando trabajas con proyectos de Python, tener un adecuado gestor de paquetes de Python hace mucho más fácil la gestión de dependencias. Necesitarás FastAPI y un servidor ASGI como Uvicorn:

pip install fastapi uvicorn[standard]

Aquí hay una aplicación FastAPI mínima:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hola Mundo"}

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

Ejecútala con:

uvicorn main:app --reload

Visita http://localhost:8000/docs para ver tu documentación de API interactiva.

Construyendo APIs listas para producción

Modelos de solicitud y respuesta

Definir modelos de datos claros es esencial para APIs mantenibles. Seguir patrones de diseño de Python para arquitectura limpia ayuda a crear aplicaciones bien estructuradas:

from pydantic import BaseModel, EmailStr, Field
from typing import Optional
from datetime import datetime

class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, max_length=50)
    email: EmailStr
    password: str = Field(..., min_length=8)

class UserResponse(BaseModel):
    id: int
    username: str
    email: str
    created_at: datetime
    
    class Config:
        orm_mode = True  # Permite que Pydantic funcione con objetos ORM

@app.post("/users/", response_model=UserResponse)
async def create_user(user: UserCreate):
    # Tu lógica empresarial aquí
    new_user = save_user_to_database(user)
    return new_user

El parámetro response_model asegura que FastAPI solo devuelva los campos especificados, filtrando automáticamente datos sensibles como contraseñas.

Inyección de dependencias

El sistema de inyección de dependencias de FastAPI es poderoso y elegante. Permite que puedas:

  • Compartir código entre endpoints
  • Imponer autenticación/autorización
  • Gestionar conexiones a bases de datos
  • Manejar dependencias complejas
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

async def get_current_user(token: str = Depends(oauth2_scheme)):
    user = verify_token(token)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Credenciales de autenticación inválidas"
        )
    return user

@app.get("/users/me")
async def read_users_me(current_user: User = Depends(get_current_user)):
    return current_user

Manejo de errores

FastAPI proporciona controladores de excepción integrados y permite respuestas de error personalizadas:

from fastapi import HTTPException

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id not in items_db:
        raise HTTPException(
            status_code=404,
            detail="Elemento no encontrado",
            headers={"X-Error": "Encabezado personalizado"}
        )
    return items_db[item_id]

Tareas en segundo plano

Para operaciones que no necesitan completarse antes de devolver una respuesta:

from fastapi import BackgroundTasks

def send_email_notification(email: str, message: str):
    # Lógica para enviar correo
    pass

@app.post("/send-notification/")
async def send_notification(
    email: str,
    background_tasks: BackgroundTasks
):
    background_tasks.add_task(send_email_notification, email, "¡Bienvenido!")
    return {"message": "Notificación programada"}

Pruebas de aplicaciones FastAPI

Las pruebas comprehensivas de Python son cruciales para APIs confiables. FastAPI funciona de forma sinérgica con pytest y proporciona un cliente de prueba:

from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_read_main():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hola Mundo"}

def test_read_item():
    response = client.get("/items/42?q=test")
    assert response.status_code == 200
    assert response.json() == {"item_id": 42, "q": "test"}

Para probar endpoints asincrónicos:

import pytest
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_async_endpoint():
    async with AsyncClient(app=app, base_url="http://test") as ac:
        response = await ac.get("/")
    assert response.status_code == 200

Integración con bases de datos

FastAPI funciona bien con varias bases de datos y ORMs. Aquí hay un ejemplo con SQLAlchemy:

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, Session
from fastapi import Depends

DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(bind=engine)
Base = declarative_base()

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True, index=True)
    username = Column(String, unique=True, index=True)
    email = Column(String, unique=True)

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.get("/users/{user_id}")
async def read_user(user_id: int, db: Session = Depends(get_db)):
    user = db.query(User).filter(User.id == user_id).first()
    if not user:
        raise HTTPException(status_code=404, detail="Usuario no encontrado")
    return user

Opciones de despliegue

Despliegue con Docker

Las aplicaciones FastAPI se contienen fácilmente. Aquí hay un Dockerfile listo para producción:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Despliegue en AWS Lambda

FastAPI funciona excelente con plataformas sin servidor. Cuando construyes un AWS Lambda dual-mode con Python y Terraform, puedes desplegar aplicaciones FastAPI usando Mangum, un adaptador que envuelve FastAPI para AWS Lambda:

from mangum import Mangum
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "¡Hola desde Lambda!"}

handler = Mangum(app)

Para despliegues más complejos, AWS SAM con Python PowerTools proporciona excelentes herramientas para aplicaciones FastAPI.

Despliegue en servidores tradicionales

Para despliegue en servidores tradicionales o Kubernetes:

# Con Gunicorn y trabajadores de Uvicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Funciones avanzadas

CORS (Cross-Origin Resource Sharing)

Habilita CORS para aplicaciones frontend:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://example.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Soporte para WebSockets

FastAPI soporta WebSockets para comunicación en tiempo real:

from fastapi import WebSocket

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Mensaje recibido: {data}")

Integración con GraphQL

FastAPI puede trabajar con GraphQL a través de Strawberry u otras bibliotecas de GraphQL:

import strawberry
from strawberry.fastapi import GraphQLRouter

@strawberry.type
class Query:
    @strawberry.field
    def hello(self) -> str:
        return "Hola Mundo"

schema = strawberry.Schema(query=Query)
graphql_app = GraphQLRouter(schema)

app.include_router(graphql_app, prefix="/graphql")

Trabajando con LLMs y IA

FastAPI es excelente para construir APIs impulsadas por IA. Cuando restringes LLMs con salida estructurada usando Ollama, los modelos Pydantic de FastAPI proporcionan definiciones de esquema perfectas para respuestas estructuradas:

from pydantic import BaseModel
from typing import List
import httpx

class SentimentResponse(BaseModel):
    sentiment: str
    confidence: float
    keywords: List[str]

@app.post("/analyze-sentiment/", response_model=SentimentResponse)
async def analyze_sentiment(text: str):
    # Llama al servicio LLM
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:11434/api/generate",
            json={
                "model": "qwen2.5",
                "prompt": f"Analizar sentimiento: {text}",
                "format": SentimentResponse.schema_json()
            }
        )
    return response.json()

Mejores prácticas y consejos

1. Usa consistentemente los decoradores de operación de ruta

Organiza tus endpoints con métodos HTTP claros:

@app.get("/items/")      # Lista elementos
@app.post("/items/")     # Crea elemento
@app.get("/items/{id}")  # Obtiene elemento específico
@app.put("/items/{id}")  # Actualiza elemento
@app.delete("/items/{id}") # Elimina elemento

2. Versiona tu API

Incluye versionamiento de API desde el principio:

from fastapi import APIRouter

api_v1 = APIRouter(prefix="/api/v1")
api_v2 = APIRouter(prefix="/api/v2")

@api_v1.get("/users/")
async def get_users_v1():
    return {"version": "1.0"}

app.include_router(api_v1)
app.include_router(api_v2)

3. Usa variables de entorno

Nunca codifiques secretos. Usa variables de entorno:

from pydantic import BaseSettings

class Settings(BaseSettings):
    database_url: str
    secret_key: str
    api_key: str
    
    class Config:
        env_file = ".env"

settings = Settings()

4. Implementa un registro adecuado

Usa el módulo de registro de Python:

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.get("/items/")
async def get_items():
    logger.info("Obteniendo todos los elementos")
    return items

5. Supervisa el rendimiento

Usa middleware para el tiempo de solicitud:

import time
from fastapi import Request

@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
    start_time = time.time()
    response = await call_next(request)
    process_time = time.time() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

FastAPI frente a otros marcos

FastAPI vs Flask

Flask es más minimalista y te da más control, pero FastAPI proporciona más características de serie:

  • FastAPI tiene validación y documentación automáticas
  • Flask requiere extensiones para soporte asincrónico
  • FastAPI es significativamente más rápido para operaciones acotadas por I/O
  • Flask tiene un ecosistema más grande y más recursos de aprendizaje

FastAPI vs Django REST Framework

Django REST Framework (DRF) forma parte del ecosistema más grande de Django:

  • DRF incluye una ORM completa y una interfaz de administración
  • FastAPI es más ligero y rápido
  • DRF es mejor para aplicaciones complejas y pesadas en base de datos
  • FastAPI destaca en microservicios y APIs independientes

FastAPI vs Node.js/Express

FastAPI ofrece la simplicidad de Python con un rendimiento comparable al de Node.js:

  • Características similares de rendimiento asincrónico
  • El sistema de tipo de Python es más robusto que JavaScript/TypeScript
  • Node.js tiene un ecosistema de paquetes más grande
  • La documentación automática de FastAPI es superior

Casos de uso reales

Arquitectura de microservicios

La naturaleza ligera de FastAPI y su tiempo de inicio rápido lo hacen ideal para microservicios. Cada servicio puede desplegarse y escalarse de forma independiente.

APIs de aprendizaje automático

Servir modelos de ML es un caso de uso común de FastAPI. El soporte asincrónico del marco maneja eficientemente múltiples solicitudes de predicción.

Backend para aplicaciones móviles/web

FastAPI sirve como un excelente backend para aplicaciones modernas de SPA (Single Page Applications) y móviles gracias a su manejo automático de CORS y soporte de WebSockets.

Recolección de datos de IoT

FastAPI puede manejar la ingesta de alto volumen de datos de dispositivos IoT, procesando y almacenando datos de sensores de forma eficiente.

Chatbots y IA conversacional

Construir interfaces conversacionales y backends de chatbots se benefician del soporte de WebSockets y capacidades asincrónicas de FastAPI.

Peligros comunes y soluciones

1. Operaciones bloqueantes en funciones asincrónicas

Problema: Ejecutar código bloqueante sincrónico en funciones asincrónicas:

@app.get("/slow")
async def slow_endpoint():
    time.sleep(10)  # Bloquea todo el bucle de eventos!
    return {"status": "hecho"}

Solución: Usa run_in_executor para operaciones bloqueantes:

from fastapi import BackgroundTasks
import asyncio

@app.get("/fast")
async def fast_endpoint():
    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(None, blocking_function)
    return {"result": result}

2. No usar modelos de respuesta

Problema: Devolver objetos de base de datos crudos expone la estructura interna.

Solución: Define siempre modelos de respuesta:

@app.get("/users/{user_id}", response_model=UserResponse)
async def get_user(user_id: int):
    return db_user  # Filtrado automáticamente a través de UserResponse

3. Manejo de errores inadecuado

Problema: Excepciones no manejadas hacen que la aplicación se caiga.

Solución: Usa controladores de excepciones:

@app.exception_handler(ValueError)
async def value_error_handler(request, exc):
    return JSONResponse(
        status_code=400,
        content={"message": str(exc)}
    )

Recursos del ecosistema de Python

FastAPI funciona de forma sinérgica con el ecosistema más amplio de Python. Para una visión general completa de los fundamentos de Python, consulta el cheat sheet de Python que cubre la sintaxis esencial de Python y patrones que usarás en aplicaciones FastAPI.

Conclusión

FastAPI representa un salto significativo en el diseño de marcos web de Python. Al adoptar características modernas de Python como sugerencias de tipo y async/await, entrega un rendimiento excepcional y una experiencia del desarrollador. Ya sea que estés construyendo una API REST simple o una arquitectura compleja de microservicios, FastAPI proporciona las herramientas y el rendimiento que necesitas para aplicaciones de producción.

La automatización de la documentación, la seguridad de tipo y el diseño intuitivo lo hacen una excelente opción tanto para principiantes como para desarrolladores experimentados. A medida que el ecosistema de Python continúe evolucionando, FastAPI se posiciona como el marco para el desarrollo de APIs modernas.

Empieza con un API simple, explora la documentación y adopta gradualmente características más avanzadas a medida que tu aplicación crece. La comunidad de FastAPI es activa y útil, con documentación extensa y ejemplos para guiarte.

Enlaces útiles

Recursos externos y referencias