HATEOAS es un acrónimo de Hypermedia as the Engine of Application State. El objetivo de HATEOAS es que las operaciones que se pueden realizar con un API sean auto-descubribles a través de hipervínculos que el propio API sirve al cliente. De esta forma, el cliente REST no necesita conocer de antemano la forma de interactuar con el servidor, tan sólo debe saber interpretar los hipervínculos.
Por ejemplo, cuando el API sirve una colección de elementos puede añadir al mensaje una lista de hipervínculos para paginar la colección. Si el API devuelve una lista de localidades a través del endpoint /localities y estamos en la tercera página de un listado con 25 elementos por página y un total de 132 elementos, éste podría añadir al final de la respuesta los siguientes hipervínculos:
{
...
"data" : [
..../*the list of localities paginated*/
],
"links" : [
{
"rel" : "previous",
"href": "https://api.domain.com/v1/localities?offset=50&limit=25"
},
{
"rel" : "next",
"href": "https://api.domain.com/v1/localities?offset=100&limit=25"
},
{
"rel" : "first",
"href": "https://api.domain.com/v1/localities?offset=0&limit=25"
},
{
"rel" : "last",
"href": "https://api.domain.com/v1/localities?offset=125&limit=25"
}
]
}
De esta forma el cliente, haciendo únicamente caso al tipo de relación (atributo rel del enlace) del enlace, puede saber cómo navegar a través de las distintas páginas localidades. Si las especificaciones del API cambian la nomenclatura de la paginación, siempre y cuando se mantuviese la semántica del enlace a través del tipo de relación, el cliente no tendría por qué enterarse. Así se puede desacoplar en cierta medida el cliente del servidor.
Alternativamente al uso del cuerpo del mensaje para incluir los hipervínculos, se puede usar la cabecera HTTP Link. El uso de esta cabecera puede ser muy útil desde el punto de vista del cliente ya que le evita tener que procesar el cuerpo del mensaje para acceder a los enlaces.
Se puede añadir múltiples cabeceras Link o se puede hacer con una única cabecera Link donde los valores estén concatenados con comas:
Link: https://api.domain.com/v1/localities?offset=50&limit=25; rel=previous Link: https://api.domain.com/v1/localities?offset=100&limit=25; rel=next Link: https://api.domain.com/v1/localities?offset=0&limit=25; rel=first Link: https://api.domain.com/v1/localities?offset=125&limit=25; rel=last
Link: https://api.domain.com/v1/localities?offset=50&limit=25; rel=previous, https://api.domain.com/v1/localities?offset=100&limit=25; rel=next, https://api.domain.com/v1/localities?offset=0&limit=25; rel=first, https://api.domain.com/v1/localities?offset=125&limit=25; rel=last
El uso de HATEOAS y la adopción de patrones REST, supone que el estado de la aplicación lo mantiene el cliente y que los enlaces facilitados por el servidor deben ayudar en esta tarea mostrando en cada momento todas las acciones posibles en el siguiente paso. Además se asume que todos estas acciones son descubribles desde un principio.
Esto implica que los APIs que decidan utilizar este enfoque hasta sus últimas consecuencias debieran tener un único punto de entrada desde el cuál fuese posible iniciar toda la navegación. Ese punto de entrada podría ser la raiz del API:
https://api/domain.com/
Acceder al punto de entrada debiera servir para informar al cliente de los endpoints que tuviese disponibles para iniciar las interacciones.