Clase 01 · Módulo 05
Qué es una API y cómo leer su documentación
Qué es una API y cómo leer su documentación
Qué logras en esta clase
Abres la documentación de cualquier servicio y sacas de ella lo que necesitas para llamarlo desde un flujo.
- Reconoces las cinco piezas de una petición.
- Interpretas el código de respuesta antes de adivinar.
- Usas a Claude para leer una documentación larga y sabes qué comprobar tú.
02
La puerta de servicio
Una API es la puerta de servicio de un programa: por ahí entran otros programas, sin pasar por la pantalla que usas tú.
03
Qué es una API
API es la sigla de «interfaz de programación de aplicaciones». Es el conjunto de pedidos que un servicio acepta de otros programas, con reglas fijas.
- Tú usas una tienda en línea con clics.
- Tu flujo la usa con peticiones: «dame los pedidos de hoy», «crea este cliente».
Casi todas las API que verás viajan por HTTP, el mismo protocolo de las páginas web, y responden en JSON (visto en el módulo 3).
04
Petición y respuesta
Siempre es una conversación de dos mensajes. Tu flujo pregunta, el servicio contesta. Si no preguntas, el servicio no dice nada: para que te avise por su cuenta existen los webhooks (clase 5).
05
Las cinco piezas de una petición
| Pieza | Qué responde |
|---|---|
| Método | Qué quieres hacer |
| Dirección | Sobre qué recurso |
| Parámetros | Con qué filtros o detalles |
| Cabeceras | Quién eres y en qué formato hablas |
| Cuerpo | Qué datos envías |
No todas van siempre. Una lectura simple lleva método y dirección; crear un registro suele pedir las cinco.
06
El método dice la intención
| Método | Uso habitual |
|---|---|
| GET | Leer, sin cambiar nada |
| POST | Crear algo nuevo o ejecutar una acción |
| PUT | Reemplazar un registro completo |
| PATCH | Cambiar solo algunos campos |
| DELETE | Borrar |
07
La dirección: base más ruta
Cada operación tiene una dirección, llamada también endpoint. Se arma con dos partes:
- Base: igual para todo el servicio, por ejemplo
https://api.github.com. - Ruta: el recurso puntual, por ejemplo
/repos/n8n-io/n8n/releases.
Juntas forman la dirección completa. La documentación suele mostrar la base una vez, al principio, y después solo las rutas.
08
Tres lugares para los parámetros
- En la ruta: partes variables, escritas en la documentación como
{owner}o:id. Las reemplazas por el valor real. - De consulta: después de un signo
?, como?per_page=5&page=2. Sirven para filtrar, ordenar y paginar. - En el cuerpo: los datos que envías al crear o modificar, casi siempre en JSON.
09
Cabeceras: datos sobre la petición
Las cabeceras son pares nombre y valor que acompañan la petición sin ser parte de los datos.
| Cabecera | Para qué |
|---|---|
Authorization | Llevar tu clave o token (clase 3) |
Content-Type | Decir en qué formato va el cuerpo |
Accept | Decir en qué formato quieres la respuesta |
La respuesta también trae cabeceras, y a veces dicen cosas útiles, como cuántas llamadas te quedan.
10
Primero el código, después las teorías
Toda respuesta trae un número de tres dígitos. Léelo antes de tocar nada: te dice de qué lado está el problema.
11
Los códigos que debes reconocer
| Código | Significa | Dónde mirar |
|---|---|---|
| 200, 201 | Salió bien | Los datos |
| 400 | Petición mal armada | Parámetros y cuerpo |
| 401, 403 | Credencial o permiso | La autenticación |
| 404 | No existe | La dirección |
| 429 | Demasiadas llamadas | El ritmo (clase 4) |
| 5xx | Falla del servicio | Esperar y reintentar |
Los que empiezan con 4 son tuyos; los que empiezan con 5, del otro lado.
12
El cuerpo del error también habla
Junto al código, la mayoría de los servicios devuelve un mensaje que explica qué faltó.
Copia ese mensaje completo cuando le pidas ayuda a Claude. Con el puro número, solo puede suponer.
13
Qué buscar en una documentación
- Autenticación: cómo se obtiene la clave y dónde viaja.
- Dirección base del servicio.
- La operación que necesitas: método y ruta.
- Parámetros obligatorios y opcionales.
- Ejemplo de respuesta: qué campos devuelve y con qué nombres.
- Límites de uso y cómo pagina las listas.
No se lee de corrido. Vas a esas seis cosas y dejas el resto.
14
Un ejemplo leído de punta a punta
La operación «List releases» de la API de GitHub, que es pública:
| Dato | Valor |
|---|---|
| Método | GET |
| Ruta | /repos/{owner}/{repo}/releases |
| De consulta | per_page, page |
| Respuesta | Lista de publicaciones |
Con owner igual a n8n-io y repo igual a n8n, obtienes las versiones publicadas de n8n. Sin clave, GitHub permite 60 llamadas por hora desde tu conexión.
15
curl: el ejemplo que verás en todas partes
curl es un programa de terminal para hacer peticiones HTTP. Casi toda documentación muestra sus ejemplos en ese formato.
curl -X POST https://api.ejemplo.com/v1/clientes \
-H "Authorization: Bearer TU_CLAVE" \
-H "Content-Type: application/json" \
-d '{"nombre": "Ana", "correo": "ana@ejemplo.com"}'-X es el método, -H una cabecera y -d el cuerpo. No necesitas ejecutarlo: n8n lo importa (clase 2).
16
Claude como lector de documentación
- Abre la página de la operación que te interesa, no la portada.
- Pega el texto en Claude, o entrégale el enlace si tu plan permite que lo abra.
- Dile qué quieres lograr, con un caso concreto.
- Pide método, dirección, parámetros obligatorios, autenticación y un ejemplo en curl.
- Pide que marque lo que no aparece en el texto que le diste.
17
Un pedido flojo y uno útil
| Pedido | Qué obtienes |
|---|---|
| «¿Cómo uso la API de este servicio?» | Un resumen general, a veces de memoria |
| «Con esta página que pego, dime qué petición crea un cliente con nombre y correo, y qué campos son obligatorios» | Una petición concreta que puedes probar |
La diferencia está en dar la página y el caso. Cómo redactar pedidos se trabajó en Claude de verdad; aquí solo lo aplicas.
18
Claude ahorra lectura, no comprobación
Las API cambian de versión y Claude puede recordar una antigua. La prueba real es la respuesta del servicio, no la explicación.
19
Lo que compruebas tú
- Que la ruta y los nombres de los parámetros aparecen tal cual en la documentación vigente.
- Que la versión de la API es la actual: muchas la llevan en la dirección, como
/v1/o/v2/. - Que la respuesta real trae los campos que esperabas.
- Que la operación no cobra por llamada sin que lo sepas.
20
Antes de llamar una API, mira si hace falta
| Situación | Camino |
|---|---|
| n8n tiene un nodo del servicio con esa operación | Ese nodo |
| Tiene nodo, pero no esa operación | HTTP Request con su credencial (clase 3) |
| No tiene nodo, pero sí API | HTTP Request |
| No tiene API, pero exporta archivos | Leer el archivo (módulo 3) |
| Solo tiene página web | Evaluarlo con cuidado (módulo 8) |
21
Errores comunes
- Leer la documentación de una versión antigua que quedó en el buscador.
- Dejar
{id}escrito tal cual en la ruta. - Confundir un 404 con «el servicio está caído».
- Pegar tu clave en el chat al pedir ayuda: reemplázala antes por un texto de relleno.
22
Lo que te llevas
- Una petición tiene método, dirección, parámetros, cabeceras y cuerpo.
- El código de respuesta dice de qué lado está el problema.
- De una documentación sacas seis cosas, no la lees entera.
- curl es el formato común de los ejemplos y n8n lo entiende.
- Claude resume y arma la petición; tú la compruebas contra el servicio.
23
Hazlo ahora
En 10 minutos, sin n8n:
- Abre en el navegador
https://api.github.com/repos/n8n-io/n8n/releases?per_page=2. Eso es un GET. - Ubica en la respuesta los campos
tag_nameypublished_at. - Cambia
per_page=2porper_page=5y mira qué cambia. - Cambia
n8npor un nombre inventado y lee el código y el mensaje del error. - Anota método, base, ruta y parámetros de consulta de lo que acabas de hacer.
Clase terminada
Sigue con la próxima.
Fuentes · revisadas el 18 de noviembre de 2026
- HTTP request methods (MDN Web Docs)developer.mozilla.org ↗
- HTTP response status codes (MDN Web Docs)developer.mozilla.org ↗
- GitHub REST API (documentación oficial, usada como ejemplo)docs.github.com ↗
- REST API endpoints for releases (GitHub)docs.github.com ↗
- HTTP Request (documentación de n8n)docs.n8n.io ↗