¿Deberían las API REST implementar enlaces de hipermedia HATEOAS?

En resumen

HATEOAS (Hypermedia as the Engine of Application State) es teóricamente elegante pero prácticamente complejo. La mayoría de las API omiten la implementación completa de HATEOAS y utilizan enlaces de hipermedia selectivos para la paginación, los recursos relacionados y las acciones. La Modern PetstoreAPI implementa enlaces de hipermedia prácticos sin obligar a los clientes a depender totalmente de la hipermedia.

Introducción

Estás leyendo sobre el diseño de API REST. Te encuentras con HATEOAS (Hypermedia as the Engine of Application State). La explicación dice: "Los clientes deben descubrir todas las acciones a través de enlaces de hipermedia, no codificar URLs fijas."

Piensas: "Eso suena complicado. ¿Alguien lo hace realmente?"

La respuesta: en realidad no. HATEOAS es la restricción REST más omitida. Roy Fielding (quien inventó REST) dice que es esencial. La mayoría de los diseñadores de API dicen que es poco práctico. El resultado: la mayoría de las API "REST" no son verdaderamente RESTful según la definición de Fielding.

Modern PetstoreAPI adopta un enfoque pragmático: utiliza enlaces de hipermedia donde aportan valor (paginación, recursos relacionados, acciones) pero no obliga a los clientes a depender totalmente de la hipermedia.

💡

Si estás construyendo o probando API REST, Apidog te ayuda a probar enlaces de hipermedia, validar formatos de enlace y asegurar que tu API proporciona una navegación útil. Puedes verificar la corrección de los enlaces y probar flujos de trabajo impulsados por hipermedia.

button

En esta guía, aprenderás qué es HATEOAS, por qué es controvertido y cómo implementar enlaces de hipermedia prácticos usando la Modern PetstoreAPI como referencia.

¿Qué es HATEOAS?

HATEOAS es una restricción REST que establece que los clientes deben descubrir las capacidades de la API a través de enlaces de hipermedia, no de la documentación.

El Concepto

En lugar de codificar URLs fijas:

// El cliente codifica URLs fijas
const response = await fetch('https://petstoreapi.com/v1/pets/123');
const pet = await response.json();

// El cliente conoce la estructura de la URL
await fetch(`https://petstoreapi.com/v1/pets/${pet.id}/orders`);

Los clientes siguen los enlaces de las respuestas:

// El cliente comienza en la raíz
const root = await fetch('https://petstoreapi.com/v1');
const rootData = await root.json();

// El cliente sigue el enlace a las mascotas
const petsUrl = rootData._links.pets.href;
const pets = await fetch(petsUrl);
const petsData = await pets.json();

// El cliente sigue el enlace a una mascota específica
const petUrl = petsData._links.self.href;
const pet = await fetch(petUrl);
const petData = await pet.json();

// El cliente sigue el enlace a los pedidos
const ordersUrl = petData._links.orders.href;
const orders = await fetch(ordersUrl);

La Teoría

Con HATEOAS:

1. Los clientes no codifican URLs fijas

Las URLs pueden cambiar sin romper a los clientes. El servidor controla la estructura de las URLs.

2. Los clientes descubren capacidades

Si un enlace existe, la acción está disponible. Si no, no está disponible (o no está permitida para este usuario).

3. Las API se autodocumentan

Los clientes exploran la API siguiendo enlaces, como si navegaran por un sitio web.

Ejemplo: Respuesta HATEOAS Completa

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT",
  "status": "AVAILABLE",
  "_links": {
    "self": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24"
    },
    "update": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
      "method": "PUT"
    },
    "delete": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
      "method": "DELETE"
    },
    "orders": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders"
    },
    "adopt": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/adopt",
      "method": "POST"
    }
  }
}

El cliente no necesita conocer los patrones de URL. Sigue los enlaces.

El Debate HATEOAS

HATEOAS es controvertido porque la teoría y la práctica divergen.

Argumentos a Favor de HATEOAS

1. Acoplamiento flexible

Los clientes no dependen de la estructura de la URL. El servidor puede cambiar las URLs sin romper a los clientes.

2. Descubribilidad

Los clientes pueden explorar la API sin leer la documentación.

3. Acciones impulsadas por el estado

Los enlaces muestran qué acciones están disponibles. Si una mascota es adoptada, el enlace "adoptar" desaparece.

4. REST verdadero

Roy Fielding dice que HATEOAS es esencial para REST. Sin él, no estás haciendo REST.

Argumentos en Contra de HATEOAS

1. Complejidad

Los clientes necesitan lógica de análisis de hipermedia. Los clientes HTTP simples se convierten en complejas máquinas de estado.

2. Rendimiento

Los clientes realizan múltiples solicitudes para descubrir URLs. El acceso directo a la URL es más rápido.

3. Dificultad de depuración

Seguir enlaces dificulta la depuración. No puedes simplemente usar curl en una URL; necesitas seguir la cadena de enlaces.

4. Herramientas deficientes

La mayoría de los clientes HTTP, herramientas de prueba y generadores de documentación asumen URLs codificadas.

5. Nadie lo hace

GitHub, Stripe, Twilio, Twitter—las principales API no utilizan HATEOAS completo. Si ellos no lo necesitan, ¿tú sí?

La Realidad

La mayoría de las API afirman ser "REST" pero omiten HATEOAS. En realidad, son "API HTTP" o "API similares a REST". El verdadero REST (con HATEOAS) es raro.

Enlaces de Hipermedia Prácticos

En lugar de HATEOAS completo, utiliza enlaces de hipermedia donde aporten valor.

1. Enlaces de Paginación

Problema: Los clientes necesitan construir URLs de paginación.

Solución: Proporcionar enlaces de siguiente/anterior.

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "totalPages": 10
  },
  "links": {
    "self": "https://petstoreapi.com/v1/pets?page=2&limit=20",
    "first": "https://petstoreapi.com/v1/pets?page=1&limit=20",
    "prev": "https://petstoreapi.com/v1/pets?page=1&limit=20",
    "next": "https://petstoreapi.com/v1/pets?page=3&limit=20",
    "last": "https://petstoreapi.com/v1/pets?page=10&limit=20"
  }
}

Beneficio: Los clientes no construyen URLs de paginación. Siguen los enlaces.

2. Enlaces de Recursos Relacionados

Problema: Los clientes necesitan conocer los patrones de URL para los recursos relacionados.

Solución: Proporcionar enlaces a recursos relacionados.

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "_links": {
    "self": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
    "orders": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders",
    "owner": "https://petstoreapi.com/v1/users/019b4127-54d5-76d9-b626-0d4c7bfce5b6"
  }
}

Beneficio: Los clientes descubren recursos relacionados sin necesidad de documentación.

3. Enlaces de Acción

Problema: Los clientes necesitan saber qué acciones están disponibles.

Solución: Proporcionar enlaces para las acciones disponibles.

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "status": "AVAILABLE",
  "_links": {
    "adopt": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/adopt",
      "method": "POST"
    }
  }
}

Si la mascota ya ha sido adoptada:

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "status": "ADOPTED",
  "_links": {
    // No hay enlace "adoptar" - la acción no está disponible
  }
}

Beneficio: Los enlaces indican las acciones disponibles según el estado.

4. Paginación Basada en Cursor

Problema: Los clientes necesitan construir URLs de cursor.

Solución: Proporcionar URLs opacas de siguiente/anterior.

{
  "data": [...],
  "links": {
    "next": "https://petstoreapi.com/v1/pets?cursor=eyJpZCI6IjAxOWI0MTMyIn0"
  }
}

Beneficio: Los clientes no analizan cursores. Siguen los enlaces.

Cómo la Modern PetstoreAPI Utiliza la Hipermedia

La Modern PetstoreAPI utiliza enlaces de hipermedia selectivos.

Enlaces de Paginación

Todos los endpoints de colecciones incluyen enlaces de paginación:

GET /v1/pets?limit=20

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "hasMore": true
  },
  "links": {
    "self": "https://petstoreapi.com/v1/pets?limit=20",
    "next": "https://petstoreapi.com/v1/pets?cursor=eyJpZCI6IjAxOWI0MTMyIn0&limit=20"
  }
}

Enlaces de Recursos Relacionados

Las respuestas de los recursos incluyen enlaces a recursos relacionados:

GET /v1/pets/019b4132-70aa-764f-b315-e2803d882a24

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "ownerId": "019b4127-54d5-76d9-b626-0d4c7bfce5b6",
  "_links": {
    "self": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
    "owner": "https://petstoreapi.com/v1/users/019b4127-54d5-76d9-b626-0d4c7bfce5b6",
    "orders": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders"
  }
}

Sin HATEOAS Completo

La Modern PetstoreAPI no requiere que los clientes dependan totalmente de la hipermedia. Los clientes pueden:

Opción 1: Seguir enlaces (impulsado por hipermedia)

const pet = await fetch(petUrl);
const ownerUrl = pet._links.owner.href;
const owner = await fetch(ownerUrl);

Opción 2: Construir URLs (tradicional)

const pet = await fetch(`https://petstoreapi.com/v1/pets/${petId}`);
const owner = await fetch(`https://petstoreapi.com/v1/users/${pet.ownerId}`);

Ambos enfoques funcionan. Los enlaces se proporcionan por conveniencia, no por obligación.

Probando APIs de Hipermedia con Apidog

Apidog te ayuda a probar enlaces de hipermedia y a validar la corrección de los enlaces.

Probar la Presencia de Enlaces

Verifica que las respuestas incluyan los enlaces esperados:

// Script de prueba de Apidog
pm.test("La respuesta incluye enlaces de paginación", () => {
  const links = pm.response.json().links;
  pm.expect(links).to.have.property('self');
  pm.expect(links).to.have.property('next');
});

Probar la Validez de los Enlaces

Sigue los enlaces y verifica que funcionan:

// Script de prueba de Apidog
const nextUrl = pm.response.json().links.next;

pm.sendRequest(nextUrl, (err, response) => {
  pm.test("El enlace siguiente devuelve 200", () => {
    pm.expect(response.code).to.equal(200);
  });
});

Probar el Formato de los Enlaces

Verifica que los enlaces sigan el formato esperado:

pm.test("Los enlaces son URLs absolutas", () => {
  const links = pm.response.json().links;
  Object.values(links).forEach(link => {
    pm.expect(link).to.match(/^https:\/\//);
  });
});

Cuándo Usar HATEOAS

Usa enlaces de hipermedia cuando aporten valor. Omítelos cuando no lo hagan.

Usa Enlaces de Hipermedia Para:

1. Paginación - Los clientes no deberían construir URLs de paginación

2. Recursos relacionados - Navegación conveniente

3. Acciones dependientes del estado - Mostrar acciones disponibles según el estado del recurso

4. Flujos de trabajo complejos - Guiar a los clientes a través de procesos de varios pasos

Omite HATEOAS Para:

1. API CRUD simples - Los clientes pueden construir URLs fácilmente

2. API internas - Los equipos pueden coordinar los cambios de URL

3. API críticas para el rendimiento - Los enlaces adicionales aumentan el tamaño de la respuesta

4. API móviles - El ancho de banda importa, los enlaces añaden sobrecarga

Conclusión

HATEOAS es teóricamente elegante pero prácticamente complejo. La mayoría de las API omiten la implementación completa de HATEOAS y utilizan enlaces de hipermedia selectivos donde aportan valor.

La Modern PetstoreAPI demuestra una hipermedia práctica: enlaces de paginación, enlaces a recursos relacionados y enlaces de acción, sin obligar a los clientes a depender totalmente de la hipermedia.

Usa Apidog para probar enlaces de hipermedia, validar la corrección de los enlaces y asegurar que tu API proporciona una navegación útil.

Puntos clave:

HATEOAS completo es raro y complejo
Los enlaces de hipermedia selectivos añaden valor sin complejidad
Los enlaces de paginación son la característica de hipermedia más útil
No obligues a los clientes a depender de la hipermedia
Prueba los enlaces para asegurarte de que funcionan correctamente

Explora la documentación de Modern PetstoreAPI para ver la implementación práctica de hipermedia.

button

Preguntas Frecuentes

¿Es HATEOAS obligatorio para las API REST?

Según Roy Fielding (inventor de REST), sí. En la práctica, no. La mayoría de las API "REST" omiten HATEOAS y son técnicamente "API HTTP" o "API tipo REST".

¿Qué significan las siglas HATEOAS?

Hipermedia como Motor del Estado de la Aplicación (Hypermedia as the Engine of Application State). Significa que los clientes descubren las capacidades de la API a través de enlaces de hipermedia, no de URLs codificadas.

¿Las principales API utilizan HATEOAS?

No. GitHub, Stripe, Twilio y la mayoría de las principales API no utilizan HATEOAS completo. Pueden incluir algunos enlaces de hipermedia (paginación, recursos relacionados) pero no requieren que los clientes dependan de la hipermedia.

¿Cuál es la diferencia entre HATEOAS y los enlaces de hipermedia?

HATEOAS es una restricción que requiere que los clientes dependan totalmente de la hipermedia. Los enlaces de hipermedia son simplemente enlaces en las respuestas. Puedes incluir enlaces sin imponer HATEOAS.

¿Debería implementar HATEOAS en mi API?

Probablemente no HATEOAS completo. Usa enlaces de hipermedia selectivos para la paginación y los recursos relacionados. No obligues a los clientes a depender de la hipermedia a menos que tengas una razón específica.

¿Cómo pruebo las API HATEOAS?

Usa Apidog para verificar la presencia de enlaces, seguir enlaces y validar su corrección. Prueba que los enlaces devuelvan las respuestas esperadas.

¿Cuál es el formato HAL?

HAL (Hypertext Application Language) es un formato estándar para enlaces de hipermedia. Utiliza los campos _links y _embedded. La Modern PetstoreAPI utiliza un formato de enlace inspirado en HAL.

¿Pueden los clientes ignorar los enlaces de hipermedia?

Sí. Si tu API proporciona enlaces pero no requiere que los clientes los usen, los clientes pueden construir URLs directamente. Este es el enfoque pragmático que adopta la mayoría de las API.