Curso de programación FastAPI REST

FastAPI representa una evolución significativa en el desarrollo de APIs REST con Python, combinando la simplicidad de Flask con el rendimiento de frameworks asíncronos modernos. Este framework se ha consolidado como una herramienta fundamental para crear servicios web de alto rendimiento que requieren documentación automática, validación de datos robusta y tipado estático.

Fundamentos de FastAPI

FastAPI surge como respuesta a las limitaciones de frameworks tradicionales, ofreciendo una arquitectura basada en estándares modernos como OpenAPI y JSON Schema. Su diseño aprovecha las características avanzadas de Python 3.6+, incluyendo type hints y programación asíncrona, para proporcionar una experiencia de desarrollo superior.

La filosofía de FastAPI se centra en tres pilares fundamentales: velocidad de desarrollo, rendimiento en producción y facilidad de mantenimiento. Estos principios se materializan a través de características como la generación automática de documentación, validación de datos en tiempo de ejecución y soporte nativo para operaciones asíncronas.

from fastapi import FastAPI

app = FastAPI(
    title="Mi API REST",
    description="Una API moderna con FastAPI",
    version="1.0.0"
)

@app.get("/")
async def root():
    return {"message": "Bienvenido a FastAPI"}

Arquitectura de APIs REST

El patrón REST (Representational State Transfer) define un conjunto de principios arquitectónicos para diseñar servicios web escalables. FastAPI implementa estos principios de manera natural, proporcionando herramientas específicas para cada aspecto del diseño REST.

Los métodos HTTP constituyen el vocabulario fundamental de REST, donde cada verbo tiene un propósito específico. GET para recuperar recursos, POST para crear nuevos elementos, PUT y PATCH para actualizaciones, y DELETE para eliminación. FastAPI mapea estos métodos a funciones Python de manera intuitiva.

@app.get("/usuarios/{user_id}")
async def obtener_usuario(user_id: int):
    return {"id": user_id, "nombre": "Usuario ejemplo"}

@app.post("/usuarios")
async def crear_usuario(usuario: dict):
    return {"mensaje": "Usuario creado", "datos": usuario}

Gestión de parámetros y validación

FastAPI revoluciona la gestión de parámetros mediante el uso de type hints de Python. Los path parameters se extraen automáticamente de la URL, mientras que los query parameters se manejan como argumentos de función con tipos específicos.

La validación automática elimina gran parte del código repetitivo asociado con la verificación de datos de entrada. FastAPI convierte automáticamente los tipos de datos y genera errores HTTP 422 cuando los datos no cumplen con las especificaciones.

from typing import Optional

@app.get("/productos/{producto_id}")
async def obtener_producto(
    producto_id: int,
    incluir_detalles: bool = False,
    categoria: Optional[str] = None
):
    return {
        "id": producto_id,
        "detalles": incluir_detalles,
        "categoria": categoria
    }

Pydantic: Validación

Pydantic actúa como el motor de validación de FastAPI, proporcionando un sistema robusto para definir esquemas de datos. Los modelos Pydantic no solo validan tipos, sino que también pueden aplicar reglas de negocio complejas y transformaciones de datos.

La integración con Pydantic permite crear APIs que son tanto flexibles como estrictas. Los modelos definen contratos claros entre el cliente y el servidor, mientras que la validación automática garantiza la integridad de los datos.

from pydantic import BaseModel, EmailStr, validator
from typing import Optional

class Usuario(BaseModel):
    nombre: str
    email: EmailStr
    edad: Optional[int] = None
    
    @validator('edad')
    def validar_edad(cls, v):
        if v is not None and v < 0:
            raise ValueError('La edad debe ser positiva')
        return v

@app.post("/usuarios")
async def crear_usuario(usuario: Usuario):
    return {"mensaje": "Usuario válido", "datos": usuario}

Manejo de respuestas

El manejo de respuestas en FastAPI va más allá de devolver datos simples. El framework permite controlar aspectos detallados de la respuesta HTTP, incluyendo códigos de estado, cabeceras personalizadas y formatos de contenido específicos.

Los códigos de estado HTTP comunican el resultado de cada operación de manera estándar. FastAPI facilita el uso de códigos apropiados mediante constantes predefinidas y decoradores específicos para diferentes escenarios.

from fastapi import HTTPException, status
from fastapi.responses import JSONResponse

@app.get("/usuarios/{user_id}")
async def obtener_usuario(user_id: int):
    if user_id < 1:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Usuario no encontrado"
        )
    
    return JSONResponse(
        status_code=status.HTTP_200_OK,
        content={"id": user_id, "nombre": "Usuario"}
    )

Documentación

Una de las características más destacadas de FastAPI es la generación automática de documentación. El framework crea interfaces interactivas basadas en los estándares OpenAPI y JSON Schema, eliminando la necesidad de mantener documentación separada.

La documentación interactiva no solo describe los endpoints disponibles, sino que también permite probar la API directamente desde el navegador. Esta funcionalidad acelera significativamente el desarrollo y facilita la colaboración entre equipos.

Inyección de dependencias

El sistema de dependencias de FastAPI proporciona un mecanismo elegante para gestionar recursos compartidos, autenticación, conexiones de base de datos y otros aspectos transversales de la aplicación.

Las dependencias se definen como funciones que pueden ser reutilizadas en múltiples endpoints, promoviendo la separación de responsabilidades y facilitando las pruebas unitarias.

from fastapi import Depends

def obtener_configuracion():
    return {"base_url": "https://api.ejemplo.com", "timeout": 30}

@app.get("/configuracion")
async def mostrar_config(config: dict = Depends(obtener_configuracion)):
    return config

Bases de datos

FastAPI se integra naturalmente con SQLAlchemy, el ORM más popular de Python. Esta combinación permite crear aplicaciones que manejan datos persistentes de manera eficiente y mantenible.

La arquitectura de capas típica incluye modelos SQLAlchemy para la representación de datos, esquemas Pydantic para la validación de entrada y salida, y servicios que encapsulan la lógica de negocio.

from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class UsuarioDB(Base):
    __tablename__ = "usuarios"
    
    id = Column(Integer, primary_key=True, index=True)
    nombre = Column(String, index=True)
    email = Column(String, unique=True, index=True)

Operaciones CRUD

Las operaciones CRUD (Create, Read, Update, Delete) forman la base de la mayoría de aplicaciones web. FastAPI, combinado con SQLAlchemy, proporciona patrones claros para implementar estas operaciones de manera eficiente.

Las consultas avanzadas incluyen filtrado, ordenación, paginación y joins entre tablas. SQLAlchemy ofrece tanto una interfaz de alto nivel como acceso directo a SQL cuando se requiere máximo rendimiento.

from sqlalchemy.orm import Session
from fastapi import Depends

def obtener_usuarios(
    db: Session = Depends(get_db),
    skip: int = 0,
    limit: int = 100
):
    return db.query(UsuarioDB).offset(skip).limit(limit).all()

Migraciones

Alembic gestiona la evolución del esquema de base de datos de manera controlada y versionada. Esta herramienta es esencial para mantener la consistencia de datos en entornos de producción donde el esquema debe evolucionar sin pérdida de información.

Las migraciones automáticas permiten aplicar cambios de esquema de manera incremental, facilitando el despliegue continuo y la colaboración en equipo.

# Comando para generar migración
# alembic revision --autogenerate -m "Agregar tabla usuarios"

# Comando para aplicar migraciones
# alembic upgrade head

Patrones

El desarrollo con FastAPI se beneficia de patrones arquitectónicos establecidos que promueven la mantenibilidad y escalabilidad. La separación entre controladores, servicios y repositorios crea una estructura clara que facilita las pruebas y el mantenimiento.

La gestión de errores centralizada mediante exception handlers permite manejar diferentes tipos de errores de manera consistente, proporcionando respuestas apropiadas para cada situación.

from fastapi import Request
from fastapi.responses import JSONResponse

@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
    return JSONResponse(
        status_code=400,
        content={"detail": f"Error de validación: {str(exc)}"}
    )

FastAPI representa una evolución natural en el desarrollo de APIs con Python, combinando las mejores prácticas de la industria con herramientas modernas que aceleran el desarrollo sin comprometer la calidad. Su enfoque en estándares abiertos, validación automática y documentación interactiva lo convierte en una elección ideal para proyectos que requieren APIs robustas y mantenibles.