Lección 4 de 411 min
Herramientas para APIs
Postman, Insomnia, Swagger UI, Swagger Editor, GraphiQL y AWS API Gateway.
Te pasan una API nueva con la que integrarte. Antes de escribir una línea de código quieres probar sus endpoints, guardar esas pruebas para el resto del equipo y, cuando publiques la tuya, que otros puedan explorarla sin preguntarte. Y en producción, algo tendrá que ponerse delante de tus servicios para autenticar y limitar las peticiones.
Para cada una de esas tareas hay herramientas consolidadas. En esta lección ves los clientes con los que se prueban las APIs, las herramientas que convierten un documento OpenAPI en documentación y un servicio gestionado para publicarlas.
Clientes para probar APIs
curl sirve para una petición rápida, pero cuando tienes decenas de endpoints, varios entornos y un token que caduca, necesitas algo que organice las peticiones y recuerde las variables.
Postman
El cliente de APIs más extendido: colecciones, entornos, pruebas y mocks.
- Tipo:
- Cliente de APIs
- En CI:
- Newman o Postman CLI
Postman te deja construir y enviar peticiones HTTP sin escribir código, y también admite GraphQL, gRPC y WebSocket. Las peticiones se guardan en colecciones, organizadas en carpetas, que el equipo comparte en un espacio de trabajo.
Los entornos (local, pruebas, producción) guardan variables como {{baseUrl}} o {{token}}, así que la misma colección sirve para todos: solo cambias de entorno. Cada petición puede tener scripts en JavaScript que se ejecutan antes de enviarla o después de recibir la respuesta, con pruebas como pm.test(...). Una colección se puede ejecutar entera en CI con su herramienta de línea de comandos, y también puede servir de base para un mock server que responde con los ejemplos guardados.
Úsalo cuando
Para equipos que quieren compartir un catálogo de peticiones documentadas y convertirlo en pruebas automáticas.
Ten en cuenta
Muchas funciones necesitan una cuenta y sincronizan tus colecciones con la nube de Postman: cuidado con guardar tokens o contraseñas reales en entornos compartidos. Las condiciones de los planes gratuitos cambian a menudo; revísalas antes de depender de ellas.
pm.test("Responde 200", () => {
pm.response.to.have.status(200);
});
pm.test("Devuelve un token", () => {
const cuerpo = pm.response.json();
pm.expect(cuerpo.token).to.be.a("string");
// Lo guarda para el resto de peticiones: Authorization: Bearer {{token}}
pm.environment.set("token", cuerpo.token);
});Insomnia
Un cliente de APIs de código abierto, mantenido por Kong.
- Mantiene:
- Kong
- Código:
- Abierto
Insomnia es un cliente de escritorio de código abierto que mantiene Kong, la empresa del API gateway del mismo nombre. Admite REST, GraphQL (con autocompletado a partir del esquema), gRPC y WebSocket, con entornos y variables parecidos a los de Postman.
Incluye un editor de documentos OpenAPI con vista previa y una herramienta de línea de comandos, inso, para ejecutar pruebas y comprobar especificaciones en CI. Según la versión, puedes guardar los proyectos solo en tu equipo, sincronizarlos con un repositorio Git o en la nube de Kong.
Úsalo cuando
Si prefieres un cliente de código abierto, que puedas usar sin depender de la nube y con las colecciones versionadas junto al código.
Ten en cuenta
Sus opciones de almacenamiento y de cuenta han cambiado entre versiones: antes de adoptarlo en un equipo, decide dónde se guardarán los proyectos y comprueba que todo el equipo usa la misma opción.
Entorno «local»
{ "baseUrl": "http://localhost:3000", "token": "pega-aquí-tu-token" }
Petición
GET {{ _.baseUrl }}/posts/58
Authorization: Bearer {{ _.token }}GraphiQL
El entorno de GraphQL en el navegador: escribe consultas con autocompletado.
- Mantiene:
- GraphQL Foundation
- Funciona en:
- El navegador
GraphiQL es un pequeño entorno de desarrollo para GraphQL que funciona en el navegador. Tiene un editor de consultas con autocompletado y validación mientras escribes, paneles para variables y cabeceras, historial y un explorador con la documentación de cada tipo y campo.
¿Cómo sabe qué campos existen? Por introspección: GraphQL permite preguntar al propio servidor por su esquema con una consulta especial sobre __schema. Muchos servidores GraphQL incluyen GraphiQL, u otro entorno parecido, en su URL durante el desarrollo, y también es un componente de React que puedes integrar en tu web.
Úsalo cuando
Para explorar una API GraphQL que no conoces, construir consultas antes de pasarlas al código y depurar respuestas.
Ten en cuenta
La introspección expone todo tu esquema, incluidos los campos que no pensabas anunciar. Si tu API no es pública, desactívala o protégela en producción, sin olvidar que eso no sustituye a comprobar los permisos en cada resolver.
query {
__schema {
types {
name
fields { name }
}
}
}Documentar con OpenAPI: Swagger
«Swagger» fue el nombre de la especificación antes de que pasara a llamarse OpenAPI, como viste en la lección de contratos. Hoy es una familia de herramientas de SmartBear para trabajar con esos documentos; las dos más conocidas son de código abierto.
Swagger UI
Convierte un documento OpenAPI en documentación web que se puede probar.
- Mantiene:
- SmartBear
- Entrada:
- Un documento OpenAPI
Swagger UI lee un documento OpenAPI y genera una página con todos los endpoints agrupados por etiquetas, sus parámetros, los esquemas de los datos y ejemplos. Con el botón «Try it out» rellenas los parámetros y envías una petición real desde el propio navegador; con «Authorize» introduces el token una sola vez.
Muchos frameworks la sirven casi sin configurar: FastAPI la publica en /docs, y NestJS o Spring lo hacen con un paquete adicional. También la puedes incrustar tú en cualquier web.
Úsalo cuando
Para que otros equipos o empresas descubran y prueben tu API sin instalar nada.
Ten en cuenta
«Try it out» envía peticiones de verdad: si apunta a producción y alguien prueba un DELETE, borra datos reales. Como las peticiones salen del navegador, la API también tiene que permitir ese origen en su configuración de CORS.
import fs from "node:fs";
import express from "express";
import swaggerUi from "swagger-ui-express";
import YAML from "yaml";
const app = express();
const documento = YAML.parse(fs.readFileSync("./openapi.yaml", "utf8"));
// Documentación interactiva en http://localhost:3000/docs
app.use("/docs", swaggerUi.serve, swaggerUi.setup(documento));
app.listen(3000);Swagger Editor
Un editor de OpenAPI que valida mientras escribes y muestra el resultado al lado.
- Mantiene:
- SmartBear
- En línea:
- editor.swagger.io
Swagger Editor muestra el YAML o el JSON a un lado y, al otro, la vista previa de la documentación, que se actualiza mientras escribes. Marca los errores al momento: una operación sin responses, un $ref que apunta a un esquema inexistente o un tipo mal escrito.
Puedes usarlo en la web, en editor.swagger.io, o ejecutarlo en tu propia máquina, por ejemplo con su imagen de Docker. Las versiones recientes admiten también OpenAPI 3.1 y documentos AsyncAPI.
Úsalo cuando
Cuando escribes o corriges a mano un documento OpenAPI y quieres ver los errores y el resultado sin salir del navegador.
Ten en cuenta
Comprueba que el documento sea válido, no que esté bien diseñado. Para normas propias, como exigir una descripción en cada endpoint o nombres en un estilo concreto, usa un linter de OpenAPI como Spectral, que también puedes ejecutar en CI.
paths:
/posts:
get:
summary: Lista los posts
# Error: falta «responses», obligatorio en cada operaciónPruébalo
Abre editor.swagger.io, pega el openapi.yaml de la lección de contratos y borra la línea description de la respuesta 404. Verás el error al instante y la documentación de la derecha cambiará con cada tecla.
Publicar una API
API gateway (el concepto)
Una puerta de entrada única que autentica, limita y enruta las peticiones.
- Ejemplos:
- Kong, Tyk, AWS API Gateway
Un API gateway se pone delante de tus servicios y todas las peticiones pasan por él. Envía /pedidos a un servicio y /usuarios a otro, comprueba la autenticación (claves de API, tokens JWT), aplica límites de peticiones (rate limiting), puede cachear respuestas o transformarlas, y registra métricas de todo lo que entra.
Así, cada servicio no tiene que reimplementar la autenticación ni los límites. Hay gateways que despliegas tú, como Kong o Tyk, y servicios gestionados por los proveedores cloud. Se parece a un proxy inverso, que verás en el módulo de servidores web, pero está especializado en APIs.
Úsalo cuando
Cuando expones varios servicios hacia fuera y quieres aplicar en un solo sitio la autenticación, los límites y la observabilidad.
Ten en cuenta
Es un punto único de fallo y añade algo de latencia a cada petición. Y no metas en él lógica de negocio: su trabajo es dejar pasar, o no, las peticiones.
AWS API Gateway
El API gateway gestionado de AWS, muy unido a las funciones Lambda.
- Proveedor:
- AWS
- Tipos:
- REST, HTTP y WebSocket
AWS API Gateway es un servicio gestionado: no administras servidores y escala solo. Ofrece tres tipos: REST APIs, con más funciones (claves de API y planes de uso, validación de peticiones, transformaciones, caché); HTTP APIs, más sencillas y baratas; y WebSocket APIs, que enrutan los mensajes de conexiones abiertas.
Cada ruta se conecta a una integración: lo más habitual es una función Lambda, la base de muchas arquitecturas serverless, aunque también puede reenviar a cualquier servidor HTTP o a otros servicios de AWS. Incluye throttling, que limita las peticiones por segundo y las ráfagas y responde 429 Too Many Requests al exceso, y autorización con IAM, Amazon Cognito, tokens JWT o una función Lambda propia. Puedes importar la definición desde un documento OpenAPI.
Úsalo cuando
Para exponer funciones Lambda o servicios de AWS como una API HTTPS, con autenticación y límites, sin mantener ningún servidor.
Ten en cuenta
Pagas por petición y por datos transferidos, y las integraciones tienen un tiempo máximo de respuesta: las tareas largas deben ir en segundo plano. Y la configuración queda muy atada a AWS; defínela como código, algo que verás en el módulo de infraestructura.
export const handler = async (event) => {
const post = await buscarPost(event.pathParameters.id);
if (!post) {
return { statusCode: 404, body: JSON.stringify({ error: "No existe" }) };
}
return {
statusCode: 200,
headers: { "Content-Type": "application/json" },
body: JSON.stringify(post),
};
};Interactivo
Cuatro formas de probar una API
Activa o desactiva opciones para compararlas cara a cara.
| Característica | Postman | Insomnia | GraphiQL |
|---|---|---|---|
| Qué es | Cliente de APIs completo | Cliente de APIs de código abierto | Entorno de GraphQL en el navegador |
| Protocolos | REST, GraphQL, gRPC, WebSocket y más | REST, GraphQL, gRPC y WebSocket | Solo GraphQL |
| Dónde funciona | Escritorio y web, con cuenta para casi todo | Escritorio | Lo sirve el servidor GraphQL o tu web |
| Organización | Colecciones, entornos y espacios de equipo | Proyectos y colecciones, en local, Git o la nube | Pestañas e historial |
| Pruebas automáticas | Sí: scripts con pm.test y ejecución en CI | Sí, con su CLI inso | No |
| Mejor para | Equipos que comparten y automatizan peticiones | Quien prefiere un cliente abierto y versionado con el código | Explorar un esquema y escribir consultas |
Ponlo en práctica
Saber qué es cada cosa es la mitad del trabajo. La otra mitad es reconocer cuándo usarla.
Interactivo
¿Qué usarías?
Lee cada situación y elige la opción que mejor la resuelve. Fallar aquí no cuenta: es para practicar.
Tu equipo quiere compartir treinta peticiones con variables para local, pruebas y producción, y ejecutarlas cada noche en el pipeline de CI para comprobar que la API responde bien.
Para recordar
- Postman e Insomnia te dejan probar APIs sin escribir código: organiza las peticiones en colecciones y usa entornos con variables para no duplicarlas.
- Con scripts de prueba y una herramienta de línea de comandos, una colección se convierte en pruebas automáticas que se ejecutan en CI.
- Swagger UI convierte un documento OpenAPI en documentación que se puede probar; Swagger Editor te ayuda a escribir ese documento sin errores.
- GraphiQL autocompleta gracias a la introspección; si tu esquema no es público, desactívala o protégela en producción.
- Un API gateway, como AWS API Gateway, pone en un solo sitio la autenticación, los límites de peticiones y el enrutado.
Comprueba lo aprendido
Cuestionario
Responde las 5 preguntas para completar la lección.
1.Tienes las mismas veinte peticiones para local, pruebas y producción. ¿Cómo evitas triplicarlas en Postman?
2.¿Cómo sabe GraphiQL qué campos puedes escribir para ofrecerte autocompletado?
3.¿Qué diferencia a Swagger UI de Swagger Editor?
4.Publicas Swagger UI apuntando a tu API de producción. Alguien pulsa «Try it out» en
DELETE /pedidos/{id}. ¿Qué ocurre?5.¿Para qué sirve el throttling de AWS API Gateway?