Saltar al contenido
Engineer
Menú
Diseño
Español

Engineer / Glosario

REST

estilo arquitectónico de la web, basado en recursos

Qué es

REST, abreviatura de Representational State Transfer, es el estilo arquitectónico que Roy Fielding expuso en el capítulo 5 de su tesis en 2000. No es un protocolo ni un estándar. Es un conjunto de restricciones sobre cómo pueden interactuar clientes, servidores y los intermediarios que hay entre ellos. Fielding explica qué aporta cada restricción y, en la mayoría de los casos, qué cuesta. RESTful es el adjetivo: en sentido estricto, describe un sistema que respeta todas las restricciones. En el uso cotidiano, ambos términos se amplían mucho más, hasta casi cualquier API HTTP que intercambie JSON, respete o no las restricciones siguientes.

La idea central es el recurso. En palabras de Fielding, «cualquier información que se pueda nombrar puede ser un recurso»: un documento, una imagen, un conjunto de otros recursos, una persona o incluso el tiempo que hace en una ciudad. Lo que cruza la red nunca es el recurso en sí, sino una representación: una secuencia de bytes y metadatos que describen esos bytes, como un documento HTML o una imagen JPEG. Un cliente actúa sobre un recurso enviando o recibiendo una representación de su estado actual o deseado.

Fielding construye el estilo a partir de un conjunto vacío de restricciones y las añade de una en una. Cliente-servidor separa la interfaz de usuario del almacenamiento de datos, de modo que ambos puedan evolucionar de forma independiente. La ausencia de estado significa que cada petición lleva todo lo necesario para entenderla y no depende de ningún contexto almacenado en el servidor; por tanto, el estado de sesión reside por completo en el cliente. La caché exige que cada respuesta se marque, explícita o implícitamente, como almacenable en caché o no, para que el cliente pueda reutilizar una respuesta almacenable en caché en otra petición posterior y equivalente. La interfaz uniforme, descrita más abajo, da a todos los componentes la misma interfaz general. Un sistema por capas significa que cada componente solo ve la capa con la que se comunica directamente. Así caben proxies, pasarelas y cortafuegos intermedios sin cambiar las interfaces de ambos extremos. El código bajo demanda permite a un servidor ampliar un cliente enviándole scripts para ejecutar. Fielding lo convierte en la única restricción opcional porque reduce la visibilidad.

Fielding llama a la interfaz uniforme la característica central que distingue REST de otros estilos basados en red, y la divide en cuatro restricciones: los recursos se identifican, en la web mediante URL; se manipulan a través de representaciones; los mensajes se describen a sí mismos, de modo que su significado resulta visible para cualquier intermediario; y el hipermedia es el motor del estado de la aplicación. Esto último significa que el cliente elige su siguiente transición a partir de las representaciones recibidas, igual que una persona sigue enlaces en un navegador.

Por qué importa

Cada restricción aporta algo concreto. La ausencia de estado permite a un sistema de monitorización entender una petición sin buscar fuera de ella, facilita la recuperación ante fallos parciales y permite al servidor liberar recursos en cuanto responde. Una caché puede eliminar por completo algunas interacciones. Las capas permiten a los intermediarios repartir la carga entre redes y máquinas, y a una caché en el perímetro de una organización atender a todas las personas de su interior. Como la interfaz uniforme desacopla las implementaciones de los servicios que ofrecen, un cliente y un servidor pueden cambiar sin que el otro tenga que hacerlo al mismo tiempo.

Fielding es igual de claro sobre los costes. La ausencia de estado repite en cada petición datos que un contexto compartido en el servidor habría ahorrado. Una caché puede entregar datos obsoletos. Cada capa añade sobrecarga y latencia. La interfaz uniforme reduce la eficiencia porque la información viaja con un formato estandarizado, no uno ajustado a las necesidades de una aplicación concreta. Fielding la diseñó para transferencias de datos hipermedia de grano grueso, el caso habitual en la web, y dice claramente que no es óptima para otros tipos de interacción. Ese es el terreno de las alternativas. Un servidor GraphQL recibe todas las peticiones en un único punto de entrada, identifica sus entidades por algo distinto de las URL y deja que el cliente elija exactamente qué campos recibe; gRPC, por su parte, llama a métodos declarados en una definición de servicio. Cada uno renuncia a parte de la interfaz uniforme para ajustarse a otro tipo de tráfico.

En una API HTTP, buena parte de la interfaz uniforme ya viene resuelta. HTTP define métodos con significados acordados, códigos de estado y campos de cabecera para la caché y las peticiones condicionales. Como ese significado es compartido, un proxy o una caché intermedios pueden actuar sobre un mensaje sin saber nada de esa API concreta. Una API que utiliza esos elementos según su definición obtiene esa maquinaria sin trabajo adicional. Si entrega a sus clientes plantillas de URL para rellenar en lugar de enlaces que seguir, abandona la restricción de hipermedia. Sus clientes quedan ligados a la estructura de URL del servidor: cuando cambia, dejan de funcionar. Ese es el acoplamiento que la interfaz uniforme pretende eliminar.

Cómo se aplica en la práctica

El intercambio siguiente crea un pedido y recibe como respuesta la dirección del recurso nuevo en Location y una etiqueta de entidad en ETag. La propia RFC 9110 utiliza como ejemplo un ETag en una respuesta 201: la etiqueta puede servir de validador en peticiones condicionales posteriores para impedir que dos clientes sobrescriban en silencio los cambios del otro.

POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"item": "notebook", "quantity": 2}

HTTP/1.1 201 Created
Location: /orders/7421
ETag: "v1"
Content-Type: application/json

{"id": 7421, "item": "notebook", "quantity": 2, "status": "open"}

Cada método tiene un significado en el que cualquier intermediario puede apoyarse. La RFC 9110 define GET, HEAD, OPTIONS y TRACE como seguros: el cliente no solicita ni espera ningún cambio de estado en el servidor. PUT y DELETE, junto con los métodos seguros, son idempotentes, de modo que varias peticiones idénticas tienen el mismo efecto previsto que una sola. POST no tiene ninguna de las dos propiedades, y la RFC 5789 dice lo mismo de PATCH. Esas dos propiedades permiten a un rastreador seguir enlaces sin causar daño, a una caché adelantar descargas y a un cliente repetir un PUT cuya conexión se haya cortado antes de recibir la respuesta.

Una API REST se puede manejar con un simple cliente HTTP genérico, y este sitio muestra tanto lo que ahorra como lo que cuesta. Cuando se aprovisionó un segundo servidor a partir de código, los cortafuegos de ambos proveedores cloud se configuraron directamente mediante sus API REST con una tarea HTTP genérica, en vez de una colección del proveedor. Eso elimina una dependencia y la divergencia de sus versiones, a cambio de escribir a mano la estructura de cada petición. La misma página señala un segundo coste: la tarea HTTP genérica no declara compatibilidad con el modo de comprobación, por lo que una ejecución en modo de simulación del play que crea la máquina omite todas sus tareas.

Dónde surgen los problemas

Un GET cambia algo. Una dirección como /orders/7421/cancel que cancela un pedido al consultarla rompe la promesa de que GET es seguro. La RFC 9110 explica por qué existe esa promesa: para que los rastreadores y las cachés que adelantan descargas puedan trabajar sin miedo a causar daños. El primer rastreador o caché con descarga anticipada que encuentre el enlace cancela el pedido. Ponga la acción en el método, por ejemplo mediante un POST al pedido o un PATCH de su estado.

Todas las respuestas son 200 OK. Algunas API devuelven 200 para todo y ponen el resultado real, haya error o no, en el cuerpo. Los mensajes dejan de describirse por sí mismos: las cachés, los proxies, la monitorización y las bibliotecas cliente leen el código de estado, y todos ven éxito. La RFC 9457 define un cuerpo estándar para errores, application/problem+json, con miembros como type, title, status y detail. Su miembro status es solo orientativo: el servidor debe enviar el mismo código de estado en la propia respuesta HTTP para que el software HTTP genérico, que desconoce ese formato, se comporte correctamente.

Un POST repetido crea dos pedidos. Si la conexión se corta después de que el servidor haya procesado un POST pero antes de que el cliente haya leído la respuesta, este no puede saber si el pedido existe. La RFC 9110 dice que un cliente no debería repetir automáticamente una petición no idempotente, salvo que sepa que en realidad sí lo es o pueda determinar que el primer intento no llegó a aplicarse, y que un proxy no debe hacerlo en ningún caso. También señala que algunos clientes toman la vía más arriesgada y repiten un POST de todas formas cuando la conexión se cierra antes de recibir parte alguna de la respuesta, especialmente en una conexión persistente inactiva. Una solución es permitir al cliente elegir el identificador y enviar el pedido mediante PUT a esa dirección, ya que PUT es idempotente: la primera petición crea el pedido con 201 y una repetición solo lo sustituye por el mismo estado.

Dos clientes sobrescriben los cambios del otro. Ambos leen el pedido, cada uno cambia un campo distinto y ambos envían de nuevo el contenido completo mediante PUT: la segunda escritura deshace en silencio la primera. La RFC 9110 lo llama problema de actualización perdida. La solución es devolver en If-Match la etiqueta de entidad que cada cliente recibió al leer el pedido. El servidor solo aplica el cambio si el recurso sigue en el estado que ese cliente vio por última vez. Si no es así, no debe aplicarlo y puede indicarlo con 412 Precondition Failed. Después, el cliente lee otra vez el pedido, vuelve a aplicar su cambio y lo intenta de nuevo.

PUT /orders/7421 HTTP/1.1
Host: api.example.com
If-Match: "v1"
Content-Type: application/json

{"item": "notebook", "quantity": 3, "status": "open"}

HTTP/1.1 412 Precondition Failed

El servidor recuerda la conversación. Un servidor que conserva estado por cliente entre peticiones, como la página actual de una lista o un formulario a medio completar guardado en memoria, ha abandonado la restricción de ausencia de estado. Una petición ya no se entiende por sí sola, el balanceador debe enviar cada cliente a la misma máquina y el estado se pierde al reiniciar. Se pierden precisamente las razones de Fielding para no conservarlo: visibilidad, recuperación más fácil ante fallos parciales y un servidor que puede liberar recursos al responder. Incluya el estado en la petición, por ejemplo como un token de página en la URL, o convierta lo que está a medio completar en un recurso propio, como un borrador de pedido, que cualquier servidor pueda leer.

Lecturas adicionales

Contacto

¿Aún está definiendo lo que necesita?

Cuéntenos qué está fallando o qué intenta construir. Le diremos qué haría falta, cuánto costaría aproximadamente y si somos las personas adecuadas.

Desde 1.400 DKK por hora, sin IVA; y un precio por hora menor en una contratación más larga.

welcome@engineer.company +45 50 10 61 84 Copenhague, Dinamarca