08 sept 2025·8 min
¿Qué es FastAPI? Guía práctica para construir APIs
FastAPI es un framework moderno de Python para construir APIs rápidamente, con anotaciones de tipo, validación y documentación OpenAPI automática. Aprende lo básico y sus usos.
FastAPI es un framework moderno de Python para construir APIs rápidamente, con anotaciones de tipo, validación y documentación OpenAPI automática. Aprende lo básico y sus usos.
FastAPI es un framework de Python para construir APIs web rápidamente, con código claro y documentación automática. Escribes pequeñas funciones (llamadas “endpoints”) que declaran qué datos acepta tu API y qué devuelve, y FastAPI se encarga de la parte web: enrutado, validación y producir respuestas JSON.
Una API es un conjunto de URLs que permite que un software hable con otro.
Por ejemplo, una app del tiempo en tu teléfono podría llamar a una URL como GET /weather?city=Berlin. El servidor responde con datos estructurados (normalmente JSON), como la temperatura y el pronóstico. La app del teléfono no necesita acceso directo a la base de datos del servidor: simplemente pide a la API y muestra el resultado.
FastAPI te ayuda a crear esas URLs y respuestas en Python.
No necesitas ser un experto en async para empezar; puedes escribir endpoints simples y adoptar patrones más avanzados según crezcas.
FastAPI se adoptó rápidamente porque elimina muchas fricciones habituales al construir APIs en Python.
Los proyectos tradicionales de APIs suelen empezar con una configuración lenta y mucho “plumbing”:
Las características centrales de FastAPI atacan esos problemas directamente, de modo que los equipos pasan más tiempo diseñando endpoints y menos tiempo peleando con el framework.
FastAPI se apoya fuertemente en las anotaciones de tipo de Python. Cuando declaras que un campo es un int, opcional o una lista de algo, FastAPI usa esa información para validar entradas y dar forma a las salidas.
Esto reduce errores por “usar texto donde se esperaba un número” y fomenta un comportamiento consistente en los endpoints. Sigue siendo Python, pero con expectativas más claras integradas en las firmas de función.
Como el esquema de la API se deriva del código, FastAPI puede generar documentación interactiva automáticamente (OpenAPI + Swagger UI/ReDoc). Esto es importante para la colaboración: desarrolladores frontend, QA e integradores pueden explorar endpoints, probar peticiones y ver modelos exactos sin esperar una documentación separada.
FastAPI no arreglará una API mal diseñada. Siguen siendo necesarias buenas decisiones de nombres, versionado, manejo de errores y seguridad. Lo que ofrece es un camino más limpio de “idea” a “API bien definida” con menos sorpresas.
FastAPI resulta directo una vez entiendes unas pocas ideas centrales en las que se apoya. No tienes que memorizar internals—solo reconocer las piezas que usarás a diario.
Un framework es un conjunto de herramientas y convenciones para construir una API sin empezar desde cero. FastAPI proporciona el “plumbing” para tareas comunes: definir endpoints, leer entradas, devolver salidas, manejar errores y organizar el código de forma mantenible.
Enrutado es cómo mapeas una URL y un método HTTP a un trozo de código Python.
Por ejemplo, puedes enrutar GET /users a “listar usuarios” y POST /users a “crear un usuario”. En FastAPI, normalmente defines rutas con decoradores como @app.get(...) y @app.post(...), lo que facilita ver de un vistazo qué ofrece tu API.
Cada llamada a la API es una petición (lo que envía el cliente) y una respuesta (lo que retorna tu servidor).
FastAPI te ayuda a:
/users/{id}), la cadena de consulta (?page=2), cabeceras y el cuerpo de la petición200, 201, 404)FastAPI se ejecuta sobre ASGI, un estándar moderno para servidores web en Python. En la práctica, esto significa que FastAPI está diseñado para manejar muchas conexiones eficientemente y puede soportar características como conexiones de larga duración (por ejemplo, WebSockets) sin que tengas que gestionar redes a bajo nivel.
Las anotaciones de tipo de Python (str, int, list[Item]) no son solo documentación en FastAPI: son una entrada clave. FastAPI las usa para entender qué datos esperas, convertir valores entrantes a los tipos correctos y producir APIs más predecibles.
Los modelos Pydantic te permiten definir la forma de los datos (campos, tipos, valores opcionales) en un solo lugar. FastAPI usa estos modelos para validar JSON entrante, rechazar entradas inválidas con mensajes de error útiles y serializar salidas de forma consistente—así tu API se comporta de forma fiable aun cuando los clientes envían datos desordenados.
Las apps FastAPI se construyen alrededor de endpoints: una ruta URL más un método HTTP. Piensa en un endpoint como “qué pide el cliente” y “cómo lo pide”. Por ejemplo, un cliente puede GET /users para listar usuarios, o POST /users para crear uno.
Una ruta es la ruta, y el método es la acción:
GET /products → obtener datosPOST /products → enviar datos para crear algoPUT /products/123 → reemplazar/actualizar algoDELETE /products/123 → eliminar algoFastAPI separa datos que forman parte de la ruta de datos que son filtros opcionales de la petición.
Cuando un cliente envía datos estructurados (normalmente JSON), van en el cuerpo de la petición, sobre todo con POST o PUT.
Ejemplo: POST /orders con JSON como { "item_id": 3, "quantity": 2 }.
FastAPI puede devolver objetos Python simples (como dicts), pero destaca cuando defines un modelo de respuesta. Ese modelo actúa como contrato: los campos tienen forma consistente, se pueden filtrar datos extra y se refuerzan los tipos. El resultado son APIs más limpias: los clientes saben qué esperar y evitas respuestas sorpresa que rompen integraciones.
“Async” (asíncrono) es una forma para que tu API gestione muchas peticiones eficientemente cuando mucho tiempo se pasa esperando.
Imagina un barista tomando pedidos. Si tuviera que quedarse parado hasta que la máquina termine, serviría a menos clientes. Mejor enfoque: poner el café en marcha y mientras la máquina trabaja tomar el siguiente pedido.
Async funciona así. Tu app FastAPI puede iniciar una operación que espera algo lento—como una petición de red o una consulta a la base de datos—y mientras espera puede atender otras peticiones entrantes.
Async brilla cuando tu API hace mucho trabajo de I/O (operaciones que pasan tiempo esperando en vez de “pensar”). Ejemplos comunes:
Si tus endpoints esperan frecuentemente estas operaciones, async puede mejorar el rendimiento y reducir la acumulación de peticiones bajo carga.
Async no es una varita mágica para todo. Si tu endpoint es mayormente intensivo en CPU—como redimensionar imágenes grandes, cálculos de ciencia de datos o cifrar grandes cargas—async no acelerará la computación. En esos casos necesitas otras tácticas (workers en segundo plano, process pools o escalar horizontalmente).
No tienes que reescribir todo para usar FastAPI. Puedes escribir rutas regulares (síncronas) y FastAPI las ejecutará sin problema. Muchos proyectos mezclan ambos estilos: mantén endpoints sencillos síncronos y usa async def donde claramente ayuda (normalmente alrededor de llamadas a BD o HTTP externas).
La validación es el control entre el mundo exterior y tu código. Cuando una API acepta input (cuerpo JSON, parámetros de consulta, parámetros de ruta), quieres asegurarte de que está completo, tipado correctamente y dentro de límites razonables—antes de escribir en la BD, llamar otro servicio o ejecutar lógica de negocio.
FastAPI se apoya en Pydantic para esto. Describes cómo es un “dato correcto” una vez, y FastAPI automáticamente:
Si un cliente envía datos con forma incorrecta, FastAPI responde con 422 Unprocessable Entity y un payload de error estructurado que señala el campo exacto y la razón. Esto facilita que los desarrolladores clientes arreglen las peticiones sin adivinar.
Aquí hay un pequeño modelo que muestra campos obligatorios, tipos, restricciones min/máx y formatos:
from pydantic import BaseModel, EmailStr, Field
class UserCreate(BaseModel):
email: EmailStr
age: int = Field(ge=13, le=120)
username: str = Field(min_length=3, max_length=20)
email debe estar presente.age debe ser un entero.age está limitado a 13–120.EmailStr exige una forma válida de email.Los mismos modelos pueden dar forma a la salida, de modo que las respuestas de tu API no expongan accidentalmente campos internos. Devuelves objetos Python; FastAPI (vía Pydantic) los convierte en JSON con los nombres de campo y tipos correctos.
Una de las características más prácticas de FastAPI es que genera la documentación de la API automáticamente—basada en el código que ya escribiste.
OpenAPI es una forma estándar de describir una API en un formato estructurado (normalmente JSON). Piensa en ello como un “contrato” que detalla:
GET /users/{id})Al ser legible por máquinas, herramientas pueden usarlo para generar clientes, validar peticiones y mantener al equipo alineado.
FastAPI sirve dos páginas de documentación orientadas a humanos de forma automática:
En un proyecto típico de FastAPI las encontrarás en:
/docs (Swagger UI)/redoc (ReDoc)Cuando cambias parámetros de ruta, modelos de petición, modelos de respuesta o reglas de validación, el esquema OpenAPI (y las páginas de docs) se actualizan automáticamente. No hay un paso separado de “mantener la documentación”.
Una app FastAPI puede ser pequeña y aun así sentirse “real”. Defines un objeto Python llamado app, añades un par de rutas y ejecutas un servidor local para probar en tu navegador.
Aquí está el ejemplo más pequeño útil:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"message": "Hello, FastAPI"}
Eso es todo: una ruta (GET /) que devuelve JSON.
Para que se sienta como una API, guardemos ítems en una lista. Esto no es una base de datos—los datos se reinician cuando el servidor se reinicia—pero es perfecto para aprender.
from fastapi import FastAPI
app = FastAPI()
items = []
@app.post("/items")
def create_item(name: str):
item = {"id": len(items) + 1, "name": name}
items.append(item)
item
():
items
Ahora puedes:
POST /items?name=Coffee para añadir un ítemGET /items para recuperar la listaUna estructura inicial común es:
main.py (crea app y define rutas)requirements.txt o pyproject.toml (dependencias)Normalmente:
uvicorn main:app --reload)http://127.0.0.1:8000 y pruebas los endpointsLas “dependencias” de FastAPI son entradas compartidas que tus endpoints necesitan para funcionar—cosas como una sesión de base de datos, el usuario autenticado actual, la configuración de la app o parámetros de consulta comunes. En lugar de crearlas o parsearlas en cada ruta, defines la dependencia una vez y FastAPI te la proporciona donde haga falta.
Una dependencia suele ser una función (o clase) que devuelve un valor que tu endpoint puede usar. FastAPI la llamará por ti, averiguará qué necesita (según sus parámetros) e inyectará el resultado en la función de operación de ruta.
Esto se conoce como inyección de dependencias, pero puedes pensarlo como: “declara lo que necesitas y FastAPI lo conecta”.
Sin dependencias podrías:
Con dependencias centralizas esa lógica. Si más tarde cambias cómo creas una sesión de BD o cómo cargas al usuario actual, actualizas un sitio—no docenas de endpoints.
page/limit.Aquí está el patrón conceptual que verás en muchas apps FastAPI:
from fastapi import Depends, FastAPI
app = FastAPI()
def get_settings():
return {"items_per_page": 20}
@app.get("/items")
def list_items(settings=Depends(get_settings)):
return {"limit": settings["items_per_page"]}
Declaras la dependencia con Depends(...) y FastAPI pasa su resultado al parámetro del endpoint. El mismo enfoque funciona para bloques más complejos (como get_db() o get_current_user()), ayudando a mantener tu código limpio a medida que la API crece.
FastAPI no “asegura” tu API automáticamente: eliges el esquema y lo integras en tus endpoints. La buena noticia es que FastAPI ofrece bloques de construcción (especialmente vía el sistema de dependencias) que facilitan los patrones comunes de seguridad.
Autenticación responde: “¿Quién eres?” Autorización responde: “¿Qué puedes hacer?”
Ejemplo: un usuario puede estar autenticado (login/token válido) pero no autorizado para acceder a una ruta solo para administradores.
X-API-Key). Gestionar rotación y revocación.FastAPI soporta estos patrones a través de utilidades como fastapi.security y documentándolos claramente en OpenAPI.
Si almacenas contraseñas de usuarios, nunca guardes texto plano. Almacena un hash lento y salado (por ejemplo bcrypt/argon2 vía una librería conocida). Considera también limitación de tasas y políticas de bloqueo de cuenta.
La seguridad está en los detalles: almacenamiento de tokens, configuración de CORS, uso de HTTPS, gestión de secretos y comprobaciones de autorización correctas en cada endpoint sensible. Trata las ayudas integradas como punto de partida y valida tu enfoque con revisiones y tests antes de confiar en él en producción.
Las pruebas son donde la promesa de FastAPI de “funciona en mi máquina” se convierte en confianza para desplegar. La buena noticia: FastAPI se basa en Starlette, así que tienes buenas herramientas de testing sin mucha configuración.
Tests unitarios se centran en piezas pequeñas: una función que calcula un valor, una dependencia que carga el usuario actual o un método de servicio que habla con la BD (a menudo mockeado).
Tests de integración ejercitan la API de extremo a extremo: llamas a un endpoint y compruebas la respuesta HTTP completa. Estos tests detectan errores de enrutado, inyección de dependencias y problemas de validación.
Una buena suite tiene más tests unitarios (rápidos) y menos tests de integración (mayor confianza).
Las apps FastAPI pueden probarse “como un cliente” usando TestClient de Starlette, que envía peticiones a tu app en proceso—sin servidor externo.
from fastapi.testclient import TestClient
from app.main import app
client = TestClient(app)
def test_healthcheck():
r = client.get("/health")
assert r.status_code == 200
Prueba lo que usuarios y otros sistemas esperan:
Usa datos previsibles, aísla servicios externos (mock o BD de pruebas) y evita estado compartido entre tests. Las pruebas rápidas se ejecutan; las lentas se omiten.
Poner una app FastAPI online trata principalmente de elegir el “runner” adecuado y añadir unos esenciales de producción.
Cuando ejecutas uvicorn main:app --reload localmente, usas una configuración de desarrollo: autoreload, errores verbosos y ajustes orientados a conveniencia.
En producción normalmente ejecutas Uvicorn sin reload, a menudo detrás de un gestor de procesos (como Gunicorn con workers Uvicorn) o detrás de un proxy inverso. El objetivo es estabilidad: reinicios controlados, rendimiento predecible y valores por defecto más seguros.
Un patrón común es:
Esto permite un único código desplegable en múltiples entornos sin editar archivos.
Antes de dar por terminado, confirma que tienes:
/health para monitoreo y balanceadores.Si pasas de “funciona localmente” a “listo para producción”, también ayuda estandarizar cómo generas y gestionas el contrato de la API. Algunos equipos usan la salida OpenAPI de FastAPI en workflows automatizados—por ejemplo, generar clientes, validar peticiones en CI y desplegar de forma coherente. Herramientas como Koder.ai pueden encajar en esta etapa: describir la API en chat, iterar endpoints y modelos rápidamente y luego exportar código para revisión y despliegue normal.
FastAPI es una buena elección cuando quieres una forma moderna y limpia de construir APIs REST en Python—especialmente si te importan modelos de entrada/salida claros y comportamiento predecible a medida que la API crece.
FastAPI suele brillar en:
FastAPI no siempre es la respuesta más simple:
FastAPI puede ser muy rápido en la práctica, pero la velocidad depende de tus llamadas a BD, latencia de red y lógica de negocio. Espera buen rendimiento para cargas típicas de API—solo no asumas que el framework por sí solo “arreglará” I/O lento o consultas ineficientes.
Si FastAPI te parece adecuado, enfócate en patrones de enrutado, modelos Pydantic, integración con base de datos, tareas en background y autenticación básica.
Un camino práctico es construir un pequeño conjunto de endpoints y luego ampliar con dependencias reutilizables y tests a medida que la API crece. Si quieres acelerar el scaffolding inicial (rutas, modelos y la primera estructura lista para despliegue), considera un flujo de trabajo de planificación interactiva—mapear endpoints en “modo planificación” e iterar desde una especificación. Esa es un área donde Koder.ai puede ser útil: prototipas una app guiada por la API desde chat y luego refinás el código generado para ejecutarlo como un proyecto estándar.
FastAPI es un framework web de Python para construir APIs con el mínimo código repetitivo. Escribes funciones de endpoint (por ejemplo @app.get("/users")) y FastAPI se encarga del enrutado, el parseo de peticiones, la validación y las respuestas JSON.
Un beneficio clave es que tus anotaciones de tipo y los modelos de Pydantic actúan como un contrato explícito sobre lo que la API acepta y devuelve.
Una API es un conjunto de URLs (endpoints) que otro software puede invocar para intercambiar datos.
Por ejemplo, un cliente podría solicitar datos del tiempo con GET /weather?city=Berlin, y el servidor responde con JSON estructurado. El cliente no necesita acceso directo a la base de datos: usa la respuesta de la API.
El enrutamiento asigna un método HTTP + ruta a una función de Python.
En FastAPI normalmente usas decoradores:
@app.get("/items") para operaciones de lectura@app.post("/items") para crear@app.put("/items/{id}") para actualizar/reemplazarLos parámetros de ruta forman parte de la estructura de la URL y normalmente identifican un recurso específico (son obligatorios).
GET /users/42 → 42 es un parámetro de rutaLos parámetros de consulta se añaden después de ? y suelen ser filtros u opciones opcionales.
Los modelos de Pydantic definen la forma y las reglas de tus datos (tipos, campos obligatorios, restricciones). FastAPI los utiliza para:
Si la validación falla, FastAPI normalmente responde con 422 Unprocessable Entity y un detalle sobre qué campo está mal.
FastAPI genera automáticamente un esquema OpenAPI a partir de tus endpoints, anotaciones de tipo y modelos.
Normalmente obtienes documentación interactiva de serie:
/docs/redocComo el esquema se deriva del código, la documentación se mantiene sincronizada cuando cambias parámetros o modelos.
Usa async def cuando tu endpoint pasa tiempo esperando I/O (llamadas a bases de datos, peticiones HTTP externas, acceso a almacenamiento).
Usa def cuando:
Es común mezclar endpoints síncronos y asíncronos en la misma aplicación.
Las dependencias son bloques reutilizables que FastAPI inyecta en los endpoints mediante Depends().
Se usan habitualmente para:
Reducen la repetición y centralizan lógica transversal para poder cambiarla en un único lugar.
FastAPI no asegura tu API por defecto: eliges un esquema y lo aplicas. Patrones comunes:
Recuerda también:
Para pruebas puedes usar TestClient de FastAPI/Starlette para llamar a tu API en proceso (sin servidor externo).
Cosas prácticas a comprobar:
Para despliegue, ejecuta un servidor ASGI (p. ej. Uvicorn, a veces detrás de Gunicorn o un proxy inverso) y añade esenciales de producción: logs, health checks (), timeouts y configuración por entorno.
GET /users/42 → 42 es el ID del usuario.? y típicamente es opcional.
GET /users?limit=10&active=true → limit y active controlan cómo se devuelven los resultados.@app.delete("/items/{id}") para eliminarEsto hace que la superficie de tu API sea fácil de inspeccionar directamente desde el código.
GET /users?limit=10&active=true → limit, active son parámetros de consulta/health