Curso de programación con FastAPI

Guía completa y actualizada de FastAPI para Python 3.13

Introducción a FastAPI

FastAPI es un marco de trabajo (framework) web moderno y de alto rendimiento para construir APIs con Python 3.8+ (incluyendo plena compatibilidad con Python 3.13), basado en las indicaciones de tipo (type hints) estándar de Python. Su popularidad se debe a su velocidad, facilidad de uso y características robustas.

Se fundamenta en dos componentes principales:

1. Starlette: Proporciona la base web de bajo nivel (rendimiento ASGI, WebSockets, etc.).
2. Pydantic: Gestiona la validación, serialización y deserialización de datos, utilizando las indicaciones de tipo de Python.

El propósito de FastAPI es facilitar la creación de APIs eficientes, rápidas y bien documentadas con código conciso.

Cómo funciona FastAPI: Conceptos clave

Para entender FastAPI, es importante conocer los siguientes conceptos:

1. Indicaciones de tipo (Type Hints) de Python: FastAPI utiliza extensivamente las indicaciones de tipo. Al declarar el tipo de datos de los parámetros de una función o atributos de clase, FastAPI (a través de Pydantic) las usa para:

• Validar datos entrantes.
• Serializar (convertir a JSON) datos salientes.
• Generar documentación automática.

2. Pydantic: Es una biblioteca para validación de datos. Al definir la estructura de los datos como clases que heredan de pydantic.BaseModel, se obtiene:

• Análisis (parsing) y validación de datos JSON.
• Mensajes de error claros para datos inválidos.
• Serialización de datos complejos a JSON.
• Generación de esquemas JSON Schema para los modelos.

3. Starlette: Un microframework ASGI (Asynchronous Server Gateway Interface) ligero. FastAPI lo emplea como base para gestionar peticiones y respuestas HTTP, enrutamiento, WebSockets y tareas en segundo plano. ASGI es la interfaz estándar para aplicaciones web asíncronas en Python.

4. Decoradores de operación de ruta: FastAPI usa decoradores (@app.get, @app.post, @app.put, @app.delete, etc.) para vincular funciones Python con rutas (endpoints) y métodos HTTP específicos.

5. Inyección de dependencias: Incluye un sistema de inyección de dependencias sencillo y potente, que facilita la reutilización de código, la gestión de lógica de negocio y la conexión a sistemas externos (bases de datos, autenticación).

Fortalezas destacadas de FastAPI

FastAPI presenta varias ventajas significativas:

1. Alto rendimiento: Gracias a Starlette, Pydantic y su naturaleza asíncrona (async/await), se sitúa entre los marcos de trabajo de Python más rápidos, con un rendimiento comparable al de NodeJS o Go en ciertas situaciones.
2. Desarrollo rápido: Permite escribir menos código para lograr la misma funcionalidad que otros marcos. Las indicaciones de tipo ayudan a reducir errores y tiempo de depuración.
3. Menos errores: La validación automática basada en tipos detecta muchos errores durante el desarrollo y en tiempo de ejecución.
4. Intuitivo y fácil de usar: Su API es lógica y consistente, aprovechando características modernas de Python.
5. Robusto y listo para producción: Proporciona herramientas para crear código fiable con validación, serialización y documentación integradas.
6. Documentación automática e interactiva: Genera automáticamente documentación API interactiva basada en los estándares OpenAPI (Swagger) y ReDoc. Simplemente con el código Python y sus tipos, se obtiene una interfaz de usuario (Swagger UI en /docs y ReDoc en /redoc por defecto) para probar la API.
7. Basado en estándares abiertos: Utiliza y es totalmente compatible con OpenAPI y JSON Schema.
8. Buena experiencia de desarrollador (DX): Soporte avanzado en editores (autocompletado, comprobación de tipos) gracias a las indicaciones de tipo.
9. Asíncrono por naturaleza: Soporta async def de forma nativa, ideal para operaciones de entrada/salida intensivas.
10. Inyección de dependencias integrada: Simplifica la gestión de dependencias, autenticación, conexiones a bases de datos, etc.

Primeros pasos: Un ejemplo básico

A continuación, un ejemplo mínimo para ilustrar su funcionamiento:

1. Instalación:

pip install fastapi "uvicorn[standard]"

• fastapi: El propio marco de trabajo.
• uvicorn: Un servidor ASGI rápido para ejecutar la aplicación. [standard] incluye dependencias útiles.

2. Código (main.py):

from fastapi import FastAPI
from typing import Dict, Any, Union # Union o | para tipos opcionales

# 1. Crear una instancia de FastAPI
app = FastAPI(title="Mi primera API", version="0.1.0")

# 2. Definir una operación de ruta usando un decorador
@app.get("/") # Asocia la función leer_raiz con peticiones GET a "/"
async def leer_raiz() -> Dict[str, str]:
    """
    Endpoint raíz que devuelve un saludo.
    """
    return {"mensaje": "¡Hola desde FastAPI!"}

# 3. Otra ruta con parámetro de ruta y consulta
@app.get("/items/{item_id}")
async def leer_item(item_id: int, q: Union[str, None] = None) -> Dict[str, Any]:
    """
    Endpoint que recibe un ID de item (entero) y un parámetro de consulta opcional (q).
    """
    # FastAPI valida que item_id sea un entero.
    # q es un parámetro de consulta opcional (ej: /items/5?q=consulta)
    response = {"item_id": item_id}
    if q:
        response.update({"q": q})
    return response

3. Ejecución:

    uvicorn main:app --reload

• main: El archivo main.py.
• app: El objeto FastAPI creado en main.py.
• --reload: Reinicia el servidor automáticamente al detectar cambios (útil en desarrollo).

4. Prueba:

• Visita http://127.0.0.1:8000. Verás: {"mensaje":"¡Hola desde FastAPI!"}.
• Visita http://127.0.0.1:8000/items/42. Verás: {"item_id":42}.
• Visita http://127.0.0.1:8000/items/42?q=prueba. Verás: {"item_id":42,"q":"prueba"}.
• Visita http://127.0.0.1:8000/docs para la interfaz interactiva de Swagger UI.
• Visita http://127.0.0.1:8000/redoc para la documentación generada por ReDoc.

Creando una API REST con FastAPI: Elementos esenciales

Para construir APIs REST más completas, se utilizan:

1. Parámetros de ruta (Path Parameters): Como item_id: int. Se definen en la ruta (/items/{item_id}) y se declaran como argumentos de la función con tipos.
2. Parámetros de consulta (Query Parameters): Como q: Union[str, None] = None. Son argumentos de la función que no forman parte de la ruta. Se pueden definir tipos, valores por defecto y validaciones.
3. Cuerpos de solicitud (Request Bodies): Para operaciones como POST, PUT, PATCH, se reciben datos (normalmente JSON) en el cuerpo de la petición. Se definen con una clase que hereda de pydantic.BaseModel y se usa como tipo en un argumento.

from pydantic import BaseModel
from typing import Union # Opcional en Python 3.10+ si se usa |

class Item(BaseModel):
    nombre: str
    descripcion: Union[str, None] = None # Equivalente a str | None en Python 3.10+
    precio: float
    impuesto: Union[float, None] = None

@app.post("/items/")
async def crear_item(item: Item) -> Item:
    """
    Crea un nuevo item recibiendo datos en el cuerpo de la petición.
    FastAPI valida que el JSON recibido cumpla la estructura de Item.
    """
    # Lógica para guardar el item...
    print(f"Item recibido: {item.model_dump()}") # .dict() en Pydantic v1
    return item # FastAPI serializa el objeto Item a JSON

4. Validación automática: Pydantic valida todos los parámetros (ruta, consulta, cuerpo) según los tipos y validaciones definidas. Si falla, FastAPI devuelve un error HTTP 422 detallado.
5. Modelos de respuesta (Response Models): Se puede especificar la estructura de la respuesta con el parámetro response_model en el decorador. Esto filtra los datos de salida y mejora la documentación.

class ItemPublico(BaseModel):
    nombre: str
    precio: float

@app.get("/items/{item_id}/publico", response_model=ItemPublico)
async def leer_item_publico(item_id: int) -> Any: # El tipo de retorno puede ser Any o el modelo completo
    """
    Devuelve solo los datos públicos de un item.
    """
    # Suponiendo que obtenemos un objeto Item completo
    item_completo_db = Item(nombre="Producto X", descripcion="Secreto", precio=10.5, impuesto=1.0)
    return item_completo_db # FastAPI filtra para devolver solo nombre y precio

FastAPI y Python 3.13

FastAPI funciona perfectamente con Python 3.13. Al utilizar esta versión de Python, se aprovechan:

• Las mejoras de rendimiento y nuevas características del intérprete de Python 3.13.
• La compatibilidad con las últimas versiones de Starlette y Pydantic.
• La posibilidad de usar las sintaxis más recientes de Python en la lógica de negocio, si bien el núcleo de FastAPI no depende específicamente de características exclusivas de 3.13 más allá de las ya presentes en versiones anteriores (3.8+).

Utilizar FastAPI con Python 3.13 es una combinación adecuada para el desarrollo de APIs modernas.

Conceptos avanzados

FastAPI también incluye funcionalidades para:

• Inyección de dependencias: Gestión de recursos compartidos y lógica compleja.
• Seguridad y autenticación: Utilidades para OAuth2, JWT, claves API.
• Middleware: Ejecución de código antes y después de las peticiones.
• CORS (Cross-Origin Resource Sharing): Configuración para permitir peticiones entre dominios.
• WebSockets: Comunicación bidireccional en tiempo real.
• Tareas en segundo plano: Ejecución de operaciones tras enviar la respuesta.
• Pruebas (Testing): Facilidades para pruebas unitarias y de integración.
• Integración con bases de datos: Compatibilidad con ORMs y bibliotecas de bases de datos, especialmente las asíncronas (SQLAlchemy 2.0+, databases, Tortoise ORM).