Cada vez que consultas el tiempo en el móvil, pagas con Bizum o ves que un videojuego te avisa de una oferta, hay una petición viajando entre tu dispositivo y un servidor que no ves. Esa petición sigue unas reglas muy concretas: las de las APIs REST, el tipo de API más usado hoy en internet. Al terminar esta guía sabrás qué es una API REST, cómo se construye una petición paso a paso, y podrás hacer tu primera llamada real a una API pública sin escribir un backend entero (si aún no tienes claro por dónde empezar a programar, esa es una buena guía previa).
Las paradas de esta guía
- Qué es una API, explicado sin jerga
- Qué significa que una API sea REST
- La anatomía de una petición HTTP
- Los métodos HTTP, uno por uno
- Los códigos de estado que vas a ver todo el rato
- Cómo probar una API sin escribir backend
- Autenticación: cómo sabe la API que eres tú
Qué es una API, explicado sin jerga
Imagina un restaurante. Tú no entras a la cocina a coger la comida directamente: le pides algo al camarero, el camarero se lo dice al cocinero, y te trae el plato de vuelta. Una API (Application Programming Interface, interfaz de programación de aplicaciones) es ese camarero. Es la capa intermedia que permite que tu aplicación pida datos o acciones a otro sistema sin necesitar saber cómo funciona por dentro esa cocina.
Cuando abres una app del tiempo, la app no calcula la predicción meteorológica ella misma. Le pide esos datos a la API de un servicio meteorológico, que le responde con la información ya lista para mostrar. Lo mismo pasa cuando inicias sesión con tu cuenta de Google en una web que no es de Google: esa web está hablando con la API de Google.
Qué significa que una API sea REST
REST (Representational State Transfer) no es una tecnología ni un lenguaje: es un conjunto de convenciones que la mayoría de APIs modernas siguen para que sean predecibles, como explica la documentación oficial de HTTP de MDN Web Docs. Si una API es REST, puedes asumir varias cosas sin leer ni una línea de su documentación interna.
- Cada recurso (un usuario, un producto, un pedido) tiene su propia dirección única, llamada endpoint.
- Usas verbos HTTP estándar para decir qué quieres hacer con ese recurso: leerlo, crearlo, modificarlo o borrarlo.
- El servidor no recuerda nada de peticiones anteriores: cada petición viaja con toda la información que necesita para procesarse sola (esto se llama ser stateless).
- Las respuestas suelen llegar en un formato de texto llamado JSON, fácil de leer tanto para una persona como para un programa.
No todas las APIs son REST al cien por cien (hay quien es más estricto que otros con estas reglas), pero si entiendes estos cuatro puntos ya puedes leer la documentación de prácticamente cualquier API pública que te encuentres.
La anatomía de una petición HTTP
Toda petición a una API viaja por la misma infraestructura que cualquier otra petición en internet, y tiene, como mínimo, estas cuatro piezas:
- Endpoint: la URL exacta del recurso, por ejemplo
https://api.ejemplo.com/usuarios/24. - Método: el verbo que indica la acción (GET, POST, PUT, DELETE…).
- Headers (cabeceras): metadatos sobre la petición, como el formato que esperas recibir o tu clave de autenticación.
- Body (cuerpo): los datos que envías, normalmente en JSON, solo necesario en peticiones que crean o modifican algo.
Una petición para crear un usuario nuevo podría tener este aspecto: método POST, endpoint /usuarios, y un body como {"nombre": "Pau", "curso": "Ingeniería"}. El servidor procesa esos datos y responde con el nuevo usuario creado, normalmente incluyendo el identificador que le ha asignado.
Para verlo con datos reales, así es una petición GET a una API pública y la respuesta que devuelve:
GET https://pokeapi.co/api/v2/pokemon/pikachu
Accept: application/jsonY la respuesta, ya en formato JSON:
{
"name": "pikachu",
"height": 4,
"weight": 60
}Los métodos HTTP, uno por uno
Son solo cinco los que vas a usar el noventa por ciento del tiempo. La diferencia entre ellos no es solo semántica: también indican si es seguro repetir la misma petición varias veces (lo que se llama idempotencia).
| Método | Para qué sirve | Ejemplo | Es idempotente |
|---|---|---|---|
| GET | Leer un recurso sin modificarlo | Obtener los datos de un usuario | Sí |
| POST | Crear un recurso nuevo | Registrar un usuario nuevo | No |
| PUT | Reemplazar un recurso entero | Actualizar todos los datos de un perfil | Sí |
| PATCH | Modificar solo una parte de un recurso | Cambiar solo el email de un perfil | No necesariamente |
| DELETE | Eliminar un recurso | Borrar una cuenta | Sí |
Que un método sea idempotente significa que repetirlo cien veces produce el mismo resultado que hacerlo una sola vez. Repetir un GET nunca es un problema. Repetir un POST sin darte cuenta sí puede serlo: podrías crear el mismo pedido tres veces.
Los códigos de estado que vas a ver todo el rato
Cada respuesta de una API llega acompañada de un código de tres cifras que resume qué ha pasado, antes incluso de que mires el contenido de la respuesta.
- 200 OK: todo ha ido bien.
- 201 Created: se ha creado el recurso correctamente (típico tras un POST).
- 400 Bad Request: tu petición tiene un error, normalmente en el formato de los datos enviados.
- 401 Unauthorized: falta autenticación o no es válida (a pesar del nombre, en la práctica suele significar que no estás bien identificado, no que te falte permiso).
- 403 Forbidden: sí estás autenticado, pero no tienes permiso para hacer esa acción.
- 404 Not Found: el endpoint o el recurso no existe.
- 429 Too Many Requests: has superado el límite de peticiones permitido.
- 500 Internal Server Error: el fallo está en el servidor, no en tu petición.
Cuando algo no funciona, mirar el código de estado antes que nada te ahorra media hora de depurar tu propio código por un error que en realidad está en el servidor (o al revés).
Cómo probar una API sin escribir backend
No necesitas montar un proyecto entero para empezar a practicar con una API REST. Estas son las formas más rápidas de hacer tu primera petición real.
- El navegador: para peticiones GET simples, pegar el endpoint directamente en la barra de direcciones ya funciona.
- Herramientas visuales como Postman o Thunder Client: te permiten construir cualquier tipo de petición (POST, headers, body) sin escribir código.
- curl desde la terminal: rápido para probar algo puntual, por ejemplo
curl https://pokeapi.co/api/v2/pokemon/pikachu. - fetch en JavaScript: la forma de hacerlo ya dentro de una aplicación real con APIs REST, con código como
fetch(url).then(r => r.json()).
Por ejemplo, para probar la PokeAPI (una API pública pensada para practicar) desde la terminal:
curl https://pokeapi.co/api/v2/pokemon/pikachuY el mismo resultado, ya dentro de una página web con JavaScript:
const response = await fetch("https://pokeapi.co/api/v2/pokemon/pikachu");
const data = await response.json();
console.log(data.name); // "pikachu"
Autenticación: cómo sabe la API que eres tú
Las APIs REST públicas y gratuitas suelen dejarte hacer peticiones sin identificarte. Pero en cuanto una API mueve datos privados o tiene un coste, necesita saber quién está al otro lado.
- API key: una cadena de texto única que identifica a tu aplicación (no necesariamente a ti como persona) y que envías en cada petición, normalmente en un header, para controlar acceso y límites de uso.
- Token (Bearer token): una credencial temporal que obtienes tras iniciar sesión, con una caducidad limitada.
- OAuth: un protocolo de autorización (no solo de autenticación) que permite dar acceso limitado a tus datos, como al «iniciar sesión con Google», sin compartir tu contraseña con terceros.
Una API key nunca debería aparecer escrita directamente en código que subes a un repositorio público. Es el error de seguridad más común entre quienes empiezan, y basta un bot rastreando GitHub para que la encuentren en minutos.
Qué aprender después
Con lo anterior ya puedes leer la documentación de casi cualquier API REST y hacer tus primeras pruebas con APIs REST reales. Los siguientes pasos lógicos son:
- Practicar con APIs REST públicas gratuitas: PokeAPI, JSONPlaceholder, Agify.io o la API de OpenWeather son buenos puntos de partida.
- Aprender a usar Git y GitHub para guardar y compartir el código de tus pruebas con APIs.
- Aprender a manejar JSON en tu lenguaje (parsear, recorrer, filtrar datos).
- Entender async/await, porque las peticiones a una API tardan y tu código no puede quedarse bloqueado esperando.
- Probar un microframework como Express (JavaScript) o FastAPI (Python) para construir tu propia API, no solo consumir las de otros.
Por qué merece la pena entender las APIs REST aunque no vayas a programar backend
Aunque tu objetivo no sea crear tu propia API, entender cómo funcionan las APIs REST cambia cómo lees el resto del ecosistema tecnológico. Cuando una app dice que «se ha caído el servidor», ahora sabes que probablemente es un código 500. Cuando una integración entre dos herramientas deja de funcionar, sabes que revisar primero es la API key o el token. Y cuando lees que una empresa «lanza su API pública», entiendes exactamente qué significa: está abriendo una puerta controlada para que otros programas hablen con la suya.
Las APIs REST son, hoy, el idioma común de internet: las usan las apps del móvil, las tiendas online, los bancos y hasta los electrodomésticos conectados. Dominar sus conceptos básicos no es solo un paso técnico más en tu formación como programador, es la base que te va a acompañar en prácticamente cualquier proyecto que hagas a partir de ahora.
Preguntas frecuentes
¿Necesito saber un lenguaje concreto para usar una API?
No. Una API REST se puede consumir desde prácticamente cualquier lenguaje de programación, e incluso sin programar, usando herramientas como Postman. Lo que cambia es la sintaxis para hacer la petición, no el concepto.
¿Qué diferencia hay entre API y API REST?
API es el término general para cualquier interfaz que permite a dos programas comunicarse. REST es un estilo concreto de diseñar APIs, el más común hoy en la web, pero existen otros como SOAP o GraphQL.
¿Por qué algunas APIs piden pagar y otras son gratis?
Mantener los servidores de una API REST respondiendo peticiones tiene un coste. Muchas APIs ofrecen un nivel gratuito limitado (por ejemplo, mil peticiones al mes) y cobran a partir de cierto volumen de uso.
¿Qué es una API key y dónde la guardo?
Es tu credencial de acceso a esa API. Debe guardarse en una variable de entorno o un archivo que no subas al repositorio, nunca escrita directamente en el código fuente.
¿SOAP y GraphQL son lo mismo que REST?
No. SOAP es un protocolo más antiguo y rígido, con mensajes en XML. GraphQL es una alternativa más moderna que permite pedir exactamente los campos que necesitas en una sola petición, en lugar de recibir siempre la respuesta completa como en REST.
Deja una respuesta