¿Qué es FastAPI? Guía práctica para construir APIs

FastAPI en un minuto: la definición simple

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.

¿Qué es una API? Un ejemplo sencillo

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.

¿Para quién es FastAPI?

• Principiantes que quieren una forma moderna y guiada de construir APIs sin escribir mucho código repetitivo.
• Desarrolladores en solitario que necesitan moverse rápido mientras mantienen el código legible.
• Equipos que construyen servicios en producción y se benefician de validación estricta, contratos consistentes y buena documentación.

No necesitas ser un experto en async para empezar; puedes escribir endpoints simples y adoptar patrones más avanzados según crezcas.

Qué aprenderás en esta guía

• Qué diferencia a FastAPI de otras opciones en Python
• Cómo funcionan las peticiones y respuestas (y qué significa realmente “async”)
• Cómo funciona la validación de datos con Pydantic
• Cómo FastAPI genera docs OpenAPI (Swagger UI y ReDoc)
• Cómo estructurar apps con dependencias, seguridad, tests y conceptos básicos de despliegue

Por qué FastAPI se hizo popular

FastAPI se adoptó rápidamente porque elimina muchas fricciones habituales al construir APIs en Python.

Aborda puntos dolorosos comunes

Los proyectos tradicionales de APIs suelen empezar con una configuración lenta y mucho “plumbing”:

• Escribir manualmente (y mantener sincronizado) el parseo de peticiones, la validación y los mensajes de error
• Contratos de API poco claros—¿qué acepta y devuelve exactamente este endpoint?
• Documentación que se queda atrás respecto al código, especialmente conforme el equipo crece

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.

Las anotaciones de tipo hacen que el código actúe como contrato

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.

Documentación automática que acelera al equipo

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.

Popular, pero no mágica

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.

Conceptos clave que necesitas conocer

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.

FastAPI es un framework

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: cómo se definen los endpoints

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.

Peticiones y respuestas

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:

• Leer datos de la ruta (/users/{id}), la cadena de consulta (?page=2), cabeceras y el cuerpo de la petición
• Devolver respuestas JSON estructuradas con códigos de estado correctos (como 200, 201, 404)

ASGI (a alto nivel)

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.

Anotaciones de tipo: más que “agradable de tener”

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.

Modelos Pydantic para validación

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.

Cómo FastAPI maneja peticiones y respuestas

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.

Endpoints = rutas + métodos

Una ruta es la ruta, y el método es la acción:

• GET /products → obtener datos
• POST /products → enviar datos para crear algo
• PUT /products/123 → reemplazar/actualizar algo
• DELETE /products/123 → eliminar algo

Parámetros de ruta vs. parámetros de consulta

FastAPI separa datos que forman parte de la ruta de datos que son filtros opcionales de la petición.

• Parámetro de ruta: incluido en la estructura de la URL.
  • Ejemplo: GET /users/42 → 42 es el ID del usuario.
• Parámetro de consulta: se añade después de ? y típicamente es opcional.
  • Ejemplo: GET /users?limit=10&active=true → limit y active controlan cómo se devuelven los resultados.

Cuerpos de petición para payloads JSON

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 }.

Modelos de respuesta y salida consistente

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 en FastAPI: qué es y cuándo ayuda

“Async” (asíncrono) es una forma para que tu API gestione muchas peticiones eficientemente cuando mucho tiempo se pasa esperando.

Una analogía cotidiana: esperar I/O

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.

Cuándo el async ayuda más

Async brilla cuando tu API hace mucho trabajo de I/O (operaciones que pasan tiempo esperando en vez de “pensar”). Ejemplos comunes:

• Llamadas a bases de datos (especialmente por red)
• Llamadas a servicios externos (pagos, mapas, APIs de email)
• Leer/escribir archivos o usar almacenamiento de objetos

Si tus endpoints esperan frecuentemente estas operaciones, async puede mejorar el rendimiento y reducir la acumulación de peticiones bajo carga.

Cuándo el async no importa tanto

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).

Buena noticia: el código síncrono sigue funcionando

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).

Validación y serialización con Pydantic

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:

• rechaza entradas erróneas temprano
• convierte tipos cuando es posible (por ejemplo, convertir "42" a entero)
• devuelve respuestas JSON consistentes (serialización)

Capturar entradas inválidas temprano (con errores claros)

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.

Ejemplos comunes de validación

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)

• Campos obligatorios: email debe estar presente.
• Tipos: age debe ser un entero.
• Min/max: age está limitado a 13–120.
• Formatos: EmailStr exige una forma válida de email.

Serialización: devolver JSON limpio y predecible

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.

Documentación automática: OpenAPI, Swagger UI, ReDoc

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: un contrato legible por máquinas

OpenAPI es una forma estándar de describir una API en un formato estructurado (normalmente JSON). Piensa en ello como un “contrato” que detalla:

• qué endpoints existen (p. ej. GET /users/{id})
• qué parámetros aceptan
• cómo debe ser el cuerpo de la petición
• qué respuestas y formatos de error esperar

Al ser legible por máquinas, herramientas pueden usarlo para generar clientes, validar peticiones y mantener al equipo alineado.

Swagger UI y ReDoc: docs interactivas listas para usar

FastAPI sirve dos páginas de documentación orientadas a humanos de forma automática:

• Swagger UI (interactiva): permite probar endpoints directamente en el navegador, completar parámetros, enviar peticiones y ver respuestas.
• ReDoc (legible): una página de referencia con estilo limpio.

En un proyecto típico de FastAPI las encontrarás en:

• /docs (Swagger UI)
• /redoc (ReDoc)

Docs que se mantienen sincronizadas con tu código

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”.

Por qué esto acelera al frontend y a QA

• Los desarrolladores frontend pueden explorar endpoints de inmediato y entender campos requeridos sin esperar una especificación manual.
• QA puede probar rápidamente casos límite (campos faltantes, tipos erróneos) y ver respuestas de error exactas.
• Todos comparten la misma fuente de verdad: la API en ejecución y su contrato OpenAPI.

Tu primera app FastAPI (recorrido conceptual)

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.

1) Un endpoint mínimo de “hola”

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.

2) Añadir endpoints simples para crear/leer ítems (en memoria)

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)
    return item

@app.get("/items")
def list_items():
    return items

Ahora puedes:

• POST /items?name=Coffee para añadir un ítem
• GET /items para recuperar la lista

3) Estructura típica de un proyecto pequeño

Una estructura inicial común es:

• main.py (crea app y define rutas)
• requirements.txt o pyproject.toml (dependencias)

4) Ejecutar localmente (conceptual)

Normalmente:

1. Instalas dependencias (FastAPI + un servidor ASGI como Uvicorn)
2. Inicias el servidor de desarrollo (por ejemplo: uvicorn main:app --reload)
3. Abres http://127.0.0.1:8000 y pruebas los endpoints

Dependencias y bloques reutilizables

Las “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.

Qué es una dependencia (en términos sencillos)

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”.

Por qué reduce la repetición

Sin dependencias podrías:

• Abrir/cerrar conexiones a la BD en cada endpoint
• Repetir comprobaciones de autenticación en todas partes
• Reparsear los mismos parámetros de paginación en múltiples rutas

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.

Ejemplos comunes de dependencias

• Sesión de base de datos: crear una sesión por petición y cerrarla de forma fiable.
• Ajustes/configuración: proporcionar settings basados en variables de entorno.
• Paginación: reutilizar el parseo y validación de page/limit.
• Usuario autenticado: obtener el usuario actual desde un token y aplicar permisos.

Cómo se conectan las dependencias a los endpoints

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.

Fundamentos de seguridad: autenticación y autorización

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 vs autorización

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.

Enfoques comunes de autenticación (a alto nivel)

• API keys: sencillo para acceso servicio a servicio. Normalmente se envían por cabecera (p. ej. X-API-Key). Gestionar rotación y revocación.
• OAuth2: estándar para acceso delegado; común en “Iniciar sesión con …” o cuando la autenticación está separada de la API.
• JWT (JSON Web Tokens): usado frecuentemente como tokens bearer. Conveniente para APIs sin estado, pero debes manejar expiración, claves de firma y estrategia de revocación.

FastAPI soporta estos patrones a través de utilidades como fastapi.security y documentándolos claramente en OpenAPI.

Conceptos básicos sobre contraseñas

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.

Nota importante

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.

Testeo de aplicaciones FastAPI

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 vs tests de integració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).

La idea del TestClient

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

Qué probar (lista práctica)

Prueba lo que usuarios y otros sistemas esperan:

• Códigos de estado (200 vs 201 vs 404 vs 422)
• Errores de validación (campos faltantes, tipos erróneos, campos extra)
• Forma de la respuesta (claves presentes, tipos correctos, listas vacías)
• Casos límite (0 resultados, inputs grandes, fechas límite)
• Casos de auth (sin token, token expirado, rol insuficiente)

Mantén las pruebas rápidas y repetibles

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.

Desplegando FastAPI: opciones prácticas y checklist

Poner una app FastAPI online trata principalmente de elegir el “runner” adecuado y añadir unos esenciales de producción.

Servidores de desarrollo vs 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.

Configuración con variables de entorno

Un patrón común es:

• Guardar secretos y valores por entorno (URL de BD, API keys, orígenes permitidos) en variables de entorno.
• Mantener valores sensatos por defecto en código para uso local.
• Cargar y validar settings al inicio (a menudo vía Pydantic settings).

Esto permite un único código desplegable en múltiples entornos sin editar archivos.

Destinos comunes de despliegue (visión rápida)

• Contenedores (Docker/Kubernetes): populares para builds repetibles y escalado.
• Máquinas virtuales: simples y flexibles; útiles si gestionas tus propios servidores.
• Serverless: puede funcionar para APIs pequeñas; vigila cold starts y límites de la plataforma.

Checklist práctico de despliegue

Antes de dar por terminado, confirma que tienes:

• Logging: logs estructurados, IDs de petición (si hace falta) y niveles de log por entorno.
• Health checks: endpoints como /health para monitoreo y balanceadores.
• Manejo de errores: respuestas JSON consistentes; no exponer trazas a usuarios.
• Timeouts y límites: tamaño máximo del cuerpo, timeouts de worker y limitación de tasa donde corresponda.
• Política de docs: decide si exponer Swagger UI/ReDoc públicamente o restringirlas.

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.

Cuándo usar FastAPI (y cuándo no)

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.

Casos de uso ideales

FastAPI suele brillar en:

• Servicios internos donde los equipos necesitan iteración rápida, endpoints legibles y contratos compartidos entre servicios.
• APIs públicas que se benefician de validación estricta y manejo de errores consistente.
• Microservicios donde APIs pequeñas y enfocadas se despliegan de forma independiente.
• Prototipos y MVPs donde quieres moverte rápido sin perder estructura (validación + docs).

Cuando otra herramienta puede encajar mejor

FastAPI no siempre es la respuesta más simple:

• Si escribes un script puntual o un manejador de webhook muy pequeño, algo más ligero (o incluso Python plano) puede ser suficiente.
• Si necesitas el stack completo tipo Django (ORM integrado, admin, plantillas, ecosistema maduro), Django o Django REST Framework pueden reducir decisiones y código de integración.

Una palabra realista sobre rendimiento

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.

Próximos pasos

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.