módulo: API REST con FastAPI

En este módulo abordaremos los fundamentos para construir API REST utilizando FastAPI, un framework moderno y eficiente para desarrollar servicios web en Python 3.13. La arquitectura REST (Representational State Transfer) es un estándar ampliamente adoptado para diseñar interfaces de comunicación entre sistemas distribuidos, y FastAPI facilita su implementación con un enfoque en la simplicidad, rendimiento y escalabilidad.

Partiremos de conceptos básicos sobre qué es una API REST y cómo se estructura, para luego avanzar en la creación de endpoints, manejo de peticiones HTTP, validación de datos y documentación automática. Este recorrido está diseñado para estudiantes sin experiencia previa en desarrollo de APIs, por lo que cada concepto se introducirá de forma progresiva y con ejemplos prácticos.

fundamentos de API REST y FastAPI

Una API REST permite que aplicaciones cliente y servidor intercambien información mediante peticiones HTTP, siguiendo principios como la separación de recursos, uso de métodos estándar (GET, POST, PUT, DELETE) y representación de datos en formatos como JSON.

FastAPI se apoya en las características modernas de Python, como las anotaciones de tipos y la programación asíncrona, para ofrecer:

• Definición clara y concisa de rutas y parámetros.
• Validación automática de datos de entrada y salida.
• Documentación interactiva generada automáticamente (Swagger UI y Redoc).
• Soporte nativo para concurrencia y alto rendimiento.

estructura básica de una API con FastAPI

Comenzaremos creando una instancia de la aplicación FastAPI y definiendo rutas simples que respondan a peticiones HTTP. Por ejemplo, un endpoint que devuelva un mensaje de bienvenida:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def raiz():
    return {"mensaje": "Bienvenido a la API REST con FastAPI"}

Aquí, @app.get("/") indica que la función raiz responderá a peticiones GET en la ruta raíz. La función es asíncrona (async def), lo que permite manejar múltiples solicitudes concurrentemente sin bloquear el servidor.

manejo de rutas y parámetros

Las APIs REST suelen requerir rutas dinámicas y parámetros para filtrar o modificar la respuesta. FastAPI facilita la definición de:

• Parámetros de ruta: variables incluidas en la URL.

• Parámetros de consulta: valores opcionales que se pasan tras el signo ?.

• Cuerpos de petición: datos enviados en formato JSON para operaciones como creación o actualización.

Ejemplo de ruta con parámetro de ruta y consulta:

from fastapi import FastAPI

app = FastAPI()

@app.get("/usuarios/{usuario_id}")
async def obtener_usuario(usuario_id: int, detalle: bool = False):
    return {"usuario_id": usuario_id, "detalle": detalle}

En este caso, usuario_id es obligatorio y se extrae de la ruta, mientras que detalle es un parámetro opcional de consulta con valor por defecto False.

validación y modelado de datos con Pydantic

FastAPI integra Pydantic para validar y serializar datos de forma automática. Esto es fundamental para garantizar que las entradas y salidas cumplan con el formato esperado, evitando errores y mejorando la robustez.

Definiremos modelos que representen la estructura de los datos, por ejemplo, para crear un nuevo usuario:

from pydantic import BaseModel

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

Luego, podemos usar este modelo para recibir datos en el cuerpo de una petición POST:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

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

FastAPI validará automáticamente que el JSON recibido tenga los campos y tipos correctos, devolviendo errores claros en caso contrario.

métodos HTTP y operaciones CRUD

Una API REST típica implementa operaciones CRUD (Crear, Leer, Actualizar, Eliminar) usando los métodos HTTP correspondientes:

• GET para obtener recursos.
• POST para crear nuevos recursos.
• PUT o PATCH para modificar recursos existentes.
• DELETE para eliminar recursos.

FastAPI permite definir fácilmente estos métodos con decoradores específicos:

@app.get("/items/{item_id}")
async def leer_item(item_id: int):
    ...

@app.post("/items/")
async def crear_item(item: Item):
    ...

@app.put("/items/{item_id}")
async def actualizar_item(item_id: int, item: Item):
    ...

@app.delete("/items/{item_id}")
async def eliminar_item(item_id: int):
    ...

Este esquema será la base para construir APIs completas y funcionales.

documentación automática y pruebas interactivas

Una ventaja destacada de FastAPI es que genera automáticamente documentación interactiva accesible desde el navegador, sin necesidad de configuraciones adicionales.

Al ejecutar la aplicación, se podrá acceder a:

• Swagger UI en /docs, que permite probar los endpoints directamente.
• Redoc en /redoc, que ofrece una documentación más detallada y estructurada.

Esto facilita la comprensión y validación de la API tanto para desarrolladores como para usuarios externos.

gestión de errores y respuestas personalizadas

Para construir APIs robustas, es importante manejar adecuadamente los errores y devolver respuestas claras y coherentes.

FastAPI permite lanzar excepciones HTTP con códigos específicos y mensajes personalizados mediante HTTPException:

from fastapi import HTTPException

@app.get("/usuarios/{usuario_id}")
async def obtener_usuario(usuario_id: int):
    if usuario_id not in base_datos:
        raise HTTPException(status_code=404, detail="Usuario no encontrado")
    return base_datos[usuario_id]

También se pueden definir respuestas con códigos y formatos específicos para cada endpoint, mejorando la comunicación con el cliente.

Este módulo proporcionará las bases para que los estudiantes puedan diseñar y desarrollar APIs REST funcionales y mantenibles con FastAPI, comprendiendo desde la estructura básica hasta aspectos esenciales como validación, manejo de rutas, métodos HTTP y documentación. La progresión gradual y los ejemplos prácticos facilitarán la asimilación de conceptos y la aplicación inmediata en proyectos reales.