FastAPI REST

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 estricto 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, field_validator
from typing import Optional

class Empleado(BaseModel):
    nombre: str
    email: EmailStr
    edad: Optional[int] = None

    @field_validator('edad')
    @classmethod
    def validar_edad(cls, v: Optional[int]) -> Optional[int]:
        if v is not None and v < 0:
            raise ValueError('La edad debe ser positiva')
        return v

@app.post("/empleados")
async def crear_empleado(empleado: Empleado):
    return {"mensaje": "Empleado válido", "datos": empleado}

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"}
    )