Cada vez que una aplicación del móvil muestra el tiempo, el saldo de una cuenta o los pedidos de una tienda, casi seguro que detrás hay una API REST: una forma ordenada de que un programa le pida datos a otro a través de internet. No hace falta programar para entender cómo funciona. Basta con imaginar una red de metro en la que cada estación es un dato y cada billete dice qué quieres hacer con él.
Qué es una API REST y qué significa
Una API (interfaz de programación de aplicaciones) es un conjunto de reglas para que dos programas se entiendan. REST son las siglas de Representational State Transfer, «transferencia de estado representacional», un estilo de arquitectura que describió Roy Fielding en su tesis doctoral del año 2000. Una API REST, o API RESTful, es la que sigue ese estilo.
La idea central es sencilla: todo lo que la API ofrece se trata como un recurso (un artículo, un usuario, un pedido) con su propia dirección web, y el cliente usa los métodos de HTTP, los mismos que usa el navegador, para leerlo, crearlo, cambiarlo o borrarlo. La respuesta suele llegar en JSON, un formato de texto ligero que cualquier lenguaje de programación sabe leer.
REST no es un programa ni un protocolo que se instala: es una manera de diseñar. Por eso dos API REST pueden parecerse mucho aunque estén escritas en lenguajes distintos.
Cómo funciona una petición, paso a paso
Cuando una aplicación consulta una API REST ocurre siempre lo mismo, en este orden:
- El cliente prepara la petición. Elige la dirección del recurso (por ejemplo,
https://api.ejemplo.com/v1/pedidos/42) y el método, como GET para leer. - Añade cabeceras. Indica qué formato acepta, quién es (una clave o un token de acceso) y, si envía datos, en qué formato van.
- El servidor busca la ruta. Comprueba qué código atiende esa dirección con ese método y si el cliente tiene permiso.
- Responde con un código de estado y los datos. Un 200 si todo ha ido bien, un 404 si el recurso no existe, un 401 si falta identificarse.
Cada petición es independiente: el servidor no recuerda la anterior. Si necesita saber quién eres, se lo dices en cada viaje, igual que se valida el billete en cada torno.
Los seis principios de REST
Fielding definió unas restricciones que una arquitectura debe cumplir para considerarse REST. Conviene conocerlas porque explican por qué estas API escalan tan bien:
| Principio | Qué significa en la práctica |
|---|---|
| Cliente-servidor | La interfaz que ve el usuario y el almacenamiento de datos están separados y pueden evolucionar por su cuenta. |
| Sin estado | Cada petición lleva toda la información necesaria; el servidor no guarda sesiones entre una y otra. |
| Caché | Las respuestas indican si se pueden guardar y reutilizar, lo que ahorra viajes repetidos. |
| Interfaz uniforme | Recursos identificados por su dirección y manipulados siempre con los mismos métodos estándar. |
| Sistema por capas | Entre cliente y servidor puede haber balanceadores, cachés o pasarelas sin que el cliente lo note. |
| Código bajo demanda | Opcional: el servidor puede enviar código para que lo ejecute el cliente. |
Métodos HTTP de una API REST
Los métodos son los verbos de la conversación. Con cinco se cubre casi todo:
| Método | Para qué se usa | Respuesta habitual | ¿Repetirlo cambia algo? |
|---|---|---|---|
| GET | Leer un recurso o una lista | 200 OK | No |
| POST | Crear un recurso nuevo | 201 Created | Sí, crea otro |
| PUT | Sustituir un recurso completo | 200 OK | No |
| PATCH | Cambiar solo algunos campos | 200 OK | Depende |
| DELETE | Eliminar un recurso | 204 No Content | No |
La última columna es lo que los desarrolladores llaman idempotencia: si una petición GET, PUT o DELETE se envía dos veces por un fallo de red, el resultado final es el mismo. Con POST no, y por eso los formularios de pago avisan de que no pulses dos veces.
Códigos de estado que conviene reconocer
El número de tres cifras que devuelve el servidor resume lo que ha pasado. La primera cifra marca la familia:
- 2xx, éxito: 200 (correcto), 201 (creado), 204 (hecho, sin contenido que devolver).
- 3xx, redirección: 301 (el recurso se ha mudado para siempre), 304 (no ha cambiado, usa tu copia).
- 4xx, error del cliente: 400 (petición mal formada), 401 (falta identificarse), 403 (identificado pero sin permiso), 404 (no existe), 429 (demasiadas peticiones).
- 5xx, error del servidor: 500 (fallo interno), 503 (servicio no disponible por el momento).
Cómo se diseñan las rutas de una API REST
Una buena ruta se lee como el cartel de una estación: dice dónde estás sin necesidad de explicaciones. Estas son las normas que siguen la mayoría de equipos:
- Sustantivos en plural, sin verbos:
/articulosy no/obtenerArticulos. El verbo ya lo pone el método. - Jerarquía con barras:
/autores/7/articulosdevuelve los artículos del autor 7. - Filtros en la cadena de consulta:
/articulos?categoria=tecnologia&pagina=2. - Versión visible:
/v1/al principio permite cambiar la API sin romper las aplicaciones que ya la usan. - Minúsculas y guiones: más fáciles de leer y de escribir sin errores.
En frameworks como ASP.NET Core, Spring o Laravel la ruta se puede escribir justo encima del método que la atiende. Es lo que se llama enrutamiento por atributos:
[HttpGet("api/v1/articulos")] // lista de artículos
[HttpGet("api/v1/articulos/{id}")] // un artículo
[HttpPost("api/v1/articulos")] // crea uno nuevo
[HttpDelete("api/v1/articulos/{id}")] // lo eliminaLa ventaja es que quien lee el código ve a la vez la dirección y lo que ocurre al llamarla, sin buscar en una tabla de rutas aparte.
Un ejemplo de API REST con respuesta real
Supongamos una pequeña API de una biblioteca. Para consultar un libro, el cliente envía:
GET /v1/libros/1984 HTTP/1.1
Host: api.biblioteca-ejemplo.com
Accept: application/jsonY el servidor contesta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1984,
"titulo": "Manual de redes",
"disponible": true,
"enlaces": { "autor": "/v1/autores/31" }
}Fíjate en el campo enlaces: indica dónde seguir el viaje. Cuando una API incluye estos enlaces en sus respuestas se acerca al ideal de REST, porque el cliente descubre el camino sin tenerlo memorizado.
API REST frente a SOAP y GraphQL
| REST | SOAP | GraphQL | |
|---|---|---|---|
| Qué es | Estilo de arquitectura | Protocolo con reglas estrictas | Lenguaje de consultas |
| Formato | Normalmente JSON | XML | JSON |
| Puntos de acceso | Uno por recurso | Uno por servicio | Normalmente uno solo |
| Cuándo encaja | Servicios web y apps en general | Banca, sistemas heredados, contratos formales | Pantallas que combinan muchos datos |
GraphQL, creado en Facebook y publicado en 2015, deja que el cliente pida exactamente los campos que necesita en una sola consulta. REST sigue siendo la opción más común porque es sencilla, aprovecha la caché de HTTP y casi cualquier herramienta la entiende.
Seguridad y buenas prácticas
- Siempre por HTTPS, para que nadie lea ni altere los datos por el camino.
- Autenticación con tokens (OAuth 2.0 o claves de API) en las cabeceras, nunca en la dirección.
- Límites de uso que respondan con 429 cuando alguien hace demasiadas peticiones.
- Validar todo lo que llega antes de guardarlo, aunque el cliente sea tu propia aplicación.
- Documentar cada ruta con un estándar como OpenAPI, para que otros puedan usarla sin adivinar.
Preguntas frecuentes
¿Qué diferencia hay entre una API y una API REST?
Toda API REST es una API, pero no al revés. «API» es cualquier interfaz entre programas; una API REST es la que se diseña sobre HTTP con recursos, direcciones propias y métodos estándar.
¿Qué diferencia hay entre REST y RESTful?
En la práctica se usan como sinónimos. REST es el estilo de arquitectura y RESTful es el adjetivo para una API que lo cumple.
¿Una API REST tiene que usar JSON?
No es obligatorio. Puede devolver XML, texto o imágenes, pero JSON se ha impuesto por ser ligero y fácil de leer.
¿Para qué sirve una API REST en el día a día?
Para que aplicaciones distintas compartan datos: la app del banco con sus servidores, una tienda con su pasarela de pago o un panel con los datos de analítica de una web.
¿Qué es el enrutamiento por atributos?
Es definir la ruta de cada punto de acceso con un atributo escrito sobre el propio método, en lugar de en una tabla de rutas central. ASP.NET MVC y Web API lo incorporaron de serie en 2013 y hoy es la forma habitual de trabajar en ASP.NET Core.