API REST con FastAPI

Las API REST representan uno de los paradigmas más utilizados en el desarrollo web moderno para crear servicios que permiten la comunicación entre diferentes aplicaciones. REST (Representational State Transfer) es un estilo arquitectónico que define un conjunto de principios para diseñar servicios web escalables y mantenibles.

FastAPI es un framework web moderno y de alto rendimiento para construir APIs con Python, basado en las anotaciones de tipo estándar de Python. Su diseño permite crear APIs REST de forma rápida y eficiente, con validación automática de datos y documentación interactiva generada automáticamente.

Fundamentos de las API REST

Una API REST utiliza los métodos HTTP estándar para realizar operaciones sobre recursos. Los métodos principales son:

• GET: Obtener información de un recurso
• POST: Crear un nuevo recurso
• PUT: Actualizar completamente un recurso existente
• DELETE: Eliminar un recurso
• PATCH: Actualizar parcialmente un recurso

Los recursos se identifican mediante URLs que siguen una estructura jerárquica y predecible. Por ejemplo, /usuarios/123 representa el usuario con ID 123, mientras que /usuarios representa la colección completa de usuarios.

Configuración inicial de FastAPI

Para comenzar a trabajar con FastAPI, necesitas instalar el framework junto con un servidor ASGI como Uvicorn:

pip install fastapi uvicorn

La estructura básica de una aplicación FastAPI es sorprendentemente simple:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"mensaje": "¡Hola, mundo!"}

Este código crea una aplicación FastAPI básica con un endpoint que responde a peticiones GET en la ruta raíz. Para ejecutar la aplicación, utiliza el comando:

uvicorn main:app --reload

Creación de endpoints básicos

Los endpoints en FastAPI se definen utilizando decoradores que corresponden a los métodos HTTP. Cada decorador especifica la ruta y el método HTTP que manejará:

from fastapi import FastAPI

app = FastAPI()

# Endpoint GET simple
@app.get("/usuarios")
def obtener_usuarios():
    return [
        {"id": 1, "nombre": "Ana"},
        {"id": 2, "nombre": "Carlos"}
    ]

# Endpoint con parámetro de ruta
@app.get("/usuarios/{usuario_id}")
def obtener_usuario(usuario_id: int):
    return {"id": usuario_id, "nombre": "Usuario ejemplo"}

Los parámetros de ruta se definen entre llaves en la URL y se pasan automáticamente como argumentos a la función. FastAPI realiza la conversión de tipos automáticamente basándose en las anotaciones de tipo de Python.

Manejo de datos con modelos Pydantic

Pydantic es una biblioteca integrada en FastAPI que permite definir modelos de datos con validación automática. Los modelos se definen como clases que heredan de BaseModel:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Usuario(BaseModel):
    nombre: str
    email: str
    edad: int

@app.post("/usuarios")
def crear_usuario(usuario: Usuario):
    return {"mensaje": f"Usuario {usuario.nombre} creado correctamente"}

Cuando defines un modelo Pydantic, FastAPI automáticamente:

• Valida que los datos recibidos cumplan con el esquema definido
• Convierte los tipos de datos cuando es posible
• Genera documentación automática del esquema
• Proporciona mensajes de error detallados si la validación falla

Parámetros de consulta y validación

Los parámetros de consulta (query parameters) permiten filtrar o modificar el comportamiento de los endpoints. Se definen como parámetros opcionales en las funciones:

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/productos")
def obtener_productos(
    categoria: str = None,
    precio_max: float = Query(None, description="Precio máximo del producto"),
    limite: int = Query(10, ge=1, le=100)
):
    return {
        "categoria": categoria,
        "precio_max": precio_max,
        "limite": limite
    }

La función Query() permite añadir validaciones adicionales y metadatos a los parámetros. En el ejemplo anterior, limite debe estar entre 1 y 100, y tiene un valor por defecto de 10.

Códigos de estado HTTP

Las respuestas HTTP incluyen códigos de estado que indican el resultado de la operación. FastAPI permite especificar estos códigos de forma explícita:

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

usuarios_db = [
    {"id": 1, "nombre": "Ana"},
    {"id": 2, "nombre": "Carlos"}
]

@app.get("/usuarios/{usuario_id}")
def obtener_usuario(usuario_id: int):
    usuario = next((u for u in usuarios_db if u["id"] == usuario_id), None)
    if not usuario:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Usuario no encontrado"
        )
    return usuario

@app.post("/usuarios", status_code=status.HTTP_201_CREATED)
def crear_usuario(usuario: Usuario):
    nuevo_usuario = {"id": len(usuarios_db) + 1, **usuario.dict()}
    usuarios_db.append(nuevo_usuario)
    return nuevo_usuario

El uso de códigos de estado apropiados mejora la comunicación entre el cliente y el servidor, permitiendo que las aplicaciones cliente manejen diferentes situaciones de forma adecuada.

Documentación automática

Una de las características más destacadas de FastAPI es la generación automática de documentación interactiva. Sin configuración adicional, tu API tendrá documentación disponible en:

• /docs: Interfaz Swagger UI interactiva
• /redoc: Documentación alternativa con ReDoc

Esta documentación automática se genera basándose en:

• Los tipos de datos definidos en las funciones
• Los modelos Pydantic utilizados
• Los parámetros de consulta y sus validaciones
• Los códigos de estado especificados
• Las descripciones añadidas mediante docstrings o parámetros

La documentación permite probar los endpoints directamente desde el navegador, facilitando el desarrollo y la depuración de la API.