¿Has usado una API hoy? Probablemente sí, aunque ni te hayas dado cuenta. Abriste la app del banco, consultaste el pronóstico del tiempo, hiciste scroll en el feed: todo eso implica que varias aplicaciones se comuniquen con un servidor mediante una API. Y, en la enorme mayoría de los casos, esa conversación sigue un estilo llamado REST. Vamos a abrir la caja negra.
Una API es solo un camarero
Olvida las siglas (Application Programming Interface) por un segundo. Piensa en un restaurante. No vas a la cocina a freír tu propio huevo: hablas con el camarero, él lleva el pedido y vuelve con el plato. La API es el camarero: un intermediario con un menú fijo de cosas que puedes pedir.
Tu app (el cliente) pide algo. El servidor lo prepara y lo devuelve. Nunca tocas directamente la base de datos ni ves la cocina. Solo conoces el menú: las direcciones que puedes llamar y lo que hace cada una. Esta separación es lo que permite mantener todo de forma sostenible: el equipo de backend puede reformar la cocina entera y, mientras el menú siga siendo el mismo, tu app ni se enterará.
HTTP: el idioma de la conversación
Todo este intercambio ocurre mediante HTTP, el mismo protocolo de tu navegador. Y cada pedido lleva un método, que es el verbo de la acción:
- GET — buscar datos. «Muéstrame los usuarios». No cambia nada.
- POST — crear. «Registra este usuario nuevo».
- PUT — actualizar. «Cambia los datos de este usuario».
- DELETE — borrar. «Elimina este usuario».
La clave es que el método deja clara la intención. GET /usuarios y DELETE /usuarios/42 apuntan a la misma idea de recurso, pero hacen cosas opuestas; cualquier dev que lo lea lo entiende de inmediato, sin necesidad de documentación. Además del método y la URL, el pedido lleva headers (información adicional, como quién eres y qué formato aceptas) y, en POST y PUT, un cuerpo con los datos que estás enviando.
Status codes: el servidor responde directamente
Para cada pedido, el servidor devuelve un número de tres dígitos que indica cómo salió. No necesitas memorizar todos; basta con entender el patrón de cada rango:
- 2xx — salió bien.
200 OK(aquí está),201 Created(creé lo que pediste). - 4xx — el error fue tuyo.
400 Bad Request(enviaste algo incorrecto),401 Unauthorized(¿dónde está el login?),403 Forbidden(estás autenticado, pero no tienes permiso),404 Not Found(eso no existe). - 5xx — el error fue del servidor.
500 Internal Server Error(la cocina se incendió; no fue culpa tuya).
Con solo leer el código ya sabes hacia qué lado mirar. ¿Recibiste un 401? Comprueba el token. ¿Recibiste un 500? Tranquilo, el problema está del otro lado… y es responsabilidad del equipo de backend.
Recursos y JSON: el menú y el plato
En REST, todo gira en torno a recursos: los sustantivos de tu sistema, como usuarios, pedidos y productos. Cada recurso tiene una URL, y la URL es una ruta lógica: /usuarios es la lista completa, /usuarios/42 es el usuario con id 42 y /usuarios/42/pedidos son sus pedidos. Fíjate en que son sustantivos, nunca verbos: quien cumple el papel de verbo es el método HTTP.
Y el formato en el que casi siempre viajan estos datos es JSON. Es texto plano, legible tanto para las personas como para las máquinas:
{ "id": 42, "nombre": "Ana", "activo": true, "tags": ["admin", "beta"] }
Claves y valores, listas, números y booleanos. Básicamente, es un objeto de tu código serializado como texto para atravesar internet y reconstruirse al otro lado.
Stateless y tokens: el servidor tiene amnesia
Aquí está la trampa que confunde a todo el mundo al principio: una API REST es stateless. Es decir, el servidor no se acuerda de ti entre un pedido y otro. Cada solicitud llega desde cero, como si fuera la primera vez. No existe el «pero si acabo de iniciar sesión en la solicitud anterior»: para él, la solicitud anterior nunca existió.
Entonces, ¿cómo sabe el servidor quién eres? Se lo dices de nuevo cada vez. Después de iniciar sesión, recibes un token, una cadena larga que funciona como una credencial. Luego, en cada solicitud posterior, adjuntas ese token en un header:
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
El servidor lee la credencial, comprueba si es válida y te permite continuar (o te bloquea con un 401). Esto es lo que hace escalable a la API: cualquier servidor del grupo puede atenderte, porque todo lo que necesita para saber quién eres viene incluido en la propia solicitud.
Manos a la obra: curl y Postman
La teoría está bien, pero la mejor forma de entender una API es interactuar con ella. Dos herramientas te resuelven la vida.
curl ya viene en la terminal y va directo al grano:
bash curl -X GET https://api.exemplo.com/usuarios/42 \ -H "Authorization: Bearer SEU_TOKEN"
Un POST enviando JSON no es mucho más difícil:
bash curl -X POST https://api.exemplo.com/usuarios \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{"nome": "Ana", "ativo": true}'
El -X elige el método, cada -H es un header y -d es el cuerpo. Fíjate en que todo está ahí: método, URL, token en el header y JSON en el cuerpo. Es toda la conversación en una sola línea.
Postman, por otro lado, es la versión con interfaz gráfica: completas la URL, eliges el método en un menú desplegable, configuras los headers y el cuerpo en campos separados, pulsas Send y ves la respuesta formateada, con el status code parpadeando delante de tus ojos. Para explorar una API nueva o depurar, es difícil de superar.
Listo. Ahora, cuando leas «haz un GET a este endpoint y pasa el token en el header», ya no te sonará a chino. Solo es el camarero, el pedido y la credencial. Lo demás es práctica: elige cualquier API pública, abre Postman y empieza a interactuar con ella.
