Cómo se construye una API (Python y FastAPI)

Qué es un framework web

Un framework es un conjunto de componentes y convenciones que resuelve la infraestructura repetitiva de un tipo de aplicación, para que el desarrollador escriba solo la lógica propia. En una API web, el framework se encarga de interpretar peticiones HTTP, dirigirlas a la función correcta (enrutamiento), validar datos, serializar respuestas y manejar errores.

FastAPI es un framework de Python para construir APIs. Sus características centrales:

• Se apoya en Starlette (la capa web, compatible con ASGI) y en Pydantic (validación de datos).
• Usa las anotaciones de tipo de Python (type hints) para validar entradas y documentar el contrato sin código adicional.
• Genera automáticamente la especificación OpenAPI de la API y su documentación interactiva.
• Admite funciones síncronas y asíncronas (async def).

Arquitectura: servidor ASGI y aplicación

Una API de FastAPI se ejecuta en dos capas:

1. Servidor ASGI (por ejemplo Uvicorn): abre el puerto de red, recibe las conexiones HTTP y las traduce a llamadas Python según el estándar ASGI (Asynchronous Server Gateway Interface).
2. Aplicación (el objeto app de FastAPI): recibe cada petición del servidor, la enruta, ejecuta la función correspondiente y devuelve la respuesta.

ASGI es el sucesor asíncrono de WSGI. Permite atender muchas conexiones concurrentes en un solo proceso cuando las operaciones esperan entrada/salida (consultas a bases de datos, llamadas a otras APIs).

Anatomía de una aplicación mínima

from fastapi import FastAPI

app = FastAPI()

@app.get("/saludo")
def saludo():
    return {"mensaje": "Hola, soy tu primera API"}

• Línea 1: importa la clase FastAPI.
• Línea 3: crea la instancia de la aplicación; es el objeto que el servidor ASGI ejecuta.
• Línea 5: el decorador @app.get("/saludo") declara una operación de ruta (path operation): el método HTTP (GET) y la ruta (/saludo) que activan la función siguiente.
• Líneas 6 y 7: la función que atiende la petición. Lo que devuelve (un diccionario) se serializa a JSON y se responde con 200 OK de forma predeterminada.

Parámetros y validación

FastAPI distingue tres fuentes de datos en una petición y las valida a partir de los tipos declarados:

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class Pedido(BaseModel):
    producto: str
    cantidad: int = Field(gt=0)

@app.get("/saludo/{nombre}")
def saludo_personal(nombre: str, idioma: str = "es"):
    return {"mensaje": f"Hola, {nombre}", "idioma": idioma}

@app.post("/pedidos", status_code=201)
def crear_pedido(pedido: Pedido):
    return {"recibido": pedido}

Si los datos no cumplen el tipo o las restricciones (por ejemplo, cantidad igual a 0), FastAPI responde automáticamente 422 Unprocessable Content con el detalle de cada campo inválido, sin que la función llegue a ejecutarse.

OpenAPI y documentación automática

A partir de las rutas, los tipos y los modelos, FastAPI genera una especificación OpenAPI 3.1: un documento JSON que describe cada endpoint, sus parámetros, sus cuerpos y sus respuestas. Se expone en tres direcciones:

• /openapi.json: la especificación, útil para generar clientes en otros lenguajes o importar la API en herramientas de prueba.
• /docs: Swagger UI, documentación interactiva donde cada operación se puede ejecutar desde el navegador (Try it out → Execute).
• /redoc: ReDoc, documentación de solo lectura orientada a consulta.

La documentación se mantiene sincronizada con el código porque se deriva de él.

Ejecución en desarrollo y en producción

En desarrollo:

python -m uvicorn main:app --reload

main:app indica el módulo (main.py) y el objeto de la aplicación (app); --reload reinicia el servidor al guardar cambios. Por defecto escucha en http://127.0.0.1:8000, accesible solo desde el propio equipo.

En producción cambian varias cosas:

• Sin --reload, con varios procesos de trabajo (--workers) para aprovechar los núcleos del servidor.
• Detrás de un proxy inverso (Nginx, Caddy o el balanceador del proveedor de nube) que gestiona HTTPS y el tráfico entrante.
• Empaquetada en un contenedor para que se ejecute igual en cualquier entorno (día 5) y publicada mediante un flujo de CI/CD (día 7).

Pruebas automatizadas

FastAPI incluye TestClient, que ejecuta peticiones contra la aplicación sin levantar el servidor. Con pytest se escriben pruebas que verifican códigos de estado y contenido:

from fastapi.testclient import TestClient
from main import app

cliente = TestClient(app)

def test_saludo():
    r = cliente.get("/saludo")
    assert r.status_code == 200
    assert r.json() == {"mensaje": "Hola, soy tu primera API"}

Las pruebas convierten el contrato de la API en algo comprobable: cualquier cambio que lo rompa falla antes de llegar a producción.

Estructura de un proyecto real

Cuando la API crece, se organiza en módulos:

• Routers (APIRouter): agrupan las rutas por dominio (usuarios.py, pedidos.py) y se incluyen en la aplicación principal.
• Esquemas: modelos de Pydantic para entrada y salida, separados de los modelos de base de datos.
• Dependencias (Depends): lógica reutilizable inyectada en las rutas, como la conexión a la base de datos o la verificación del usuario autenticado.
• Configuración: variables de entorno para credenciales y parámetros; nunca dentro del código.

Práctica: tu primera API en 10 minutos

1. Instala Python 3.10 o superior desde python.org. En Windows, marca «Add python.exe to PATH».
2. Crea una carpeta de proyecto y un entorno virtual: python -m venv .venv, y actívalo (.venv\Scripts\activate en Windows, source .venv/bin/activate en macOS/Linux).
3. Instala las dependencias: python -m pip install fastapi uvicorn
4. Crea main.py con la aplicación mínima de arriba.
5. Ejecuta python -m uvicorn main:app --reload y abre http://127.0.0.1:8000/docs.
6. Despliega GET /saludo, pulsa Try it out y luego Execute: verás 200 y el cuerpo JSON.
7. Agrega la ruta /saludo/{nombre} y comprueba en /docs que aparece sola, con su parámetro documentado.

La skill gratuita primera-api incluye el proyecto completo con pruebas y la solución a los errores más comunes de instalación.

Preguntas frecuentes

¿Qué es FastAPI?

Es un framework de Python para construir APIs web. Valida los datos de entrada con Pydantic y genera automáticamente la documentación interactiva de la API a partir del código.

¿Cuánto código se necesita para crear una API con FastAPI?

Una API mínima cabe en unas pocas líneas: se importa FastAPI, se crea la aplicación y se define una función con un decorador como @app.get("/") que devuelve los datos. Se ejecuta con un servidor ASGI como Uvicorn.

¿Dónde se prueba una API hecha con FastAPI?

En la página de documentación que FastAPI genera sola en /docs (Swagger UI): ahí se ven todas las rutas y se pueden enviar peticiones desde el navegador sin instalar nada más.

¿FastAPI sirve para producción?

Sí. Se ejecuta detrás de un servidor ASGI como Uvicorn, con varios procesos de trabajo, pruebas automatizadas y, normalmente, empaquetada en un contenedor.

Referencias

• Documentación oficial de FastAPI (en español).
• Especificación ASGI.
• OpenAPI Specification 3.1.