HATEOAS

Resumen

HATEOAS es el nivel más alto de madurez en el modelo de Richardson para APIs REST. La idea es que un cliente no necesita saber las URLs de la API de antemano ni construirlas con templates. En cambio, cada respuesta incluye links que indican qué acciones puede tomar el cliente a continuación.

Si consultás GET /orders/42, la respuesta no solo contiene los datos de la orden, sino también links para cancelarla, ver sus items, o consultar el historial de pagos. El cliente descubre las operaciones disponibles dinámicamente, como un navegador web descubre links en una página HTML.

Importa porque desacopla al cliente de la estructura de URLs del servidor. Si el servidor cambia /orders/{id}/cancel a /orders/{id}/actions/cancel, el cliente no se rompe: sigue el link que recibió en la respuesta. Rara vez se implementa en su forma completa fuera de APIs hipermedia como las de PayPal o GitHub.

Alcance y supuestos

Cubre HATEOAS como restricción REST, el modelo de madurez de Richardson y ejemplos prácticos. Asume familiaridad con REST y HTTP.

Modelo mental

Un navegador web y una página HTML. Cuando entrás a una web, no necesitás saber de antemano todas las URLs del sitio. La página de inicio tiene links a "Productos", "Contacto", "Carrito". Hacés clic y navegás. HATEOAS aplica ese mismo principio a las APIs: la respuesta es la página, los links son la navegación.

Uso práctico

• ✅ APIs que evolucionan frecuentemente y no quieren romper clientes.
• ❌ APIs internas con pocos consumidores: el overhead de generar links no se justifica.

Ejemplo trabajado: respuesta HATEOAS de una orden

{
  "id": 42,
  "status": "pending",
  "_links": {
    "self": { "href": "/orders/42" },
    "cancel": { "href": "/orders/42/cancel", "method": "POST" },
    "items": { "href": "/orders/42/items" }
  }
}

Evidencia

• HATEOAS fue definido por Roy Fielding en su disertación doctoral como parte de las restricciones REST.