Últimamente he estado leyendo sobre Hipermedia como el Motor del Estado de la Aplicación (HATEOAS), la restricción que se afirma para hacer que una API web sea "verdaderamente RESTful". Básicamente se trata de incluir enlaces con cada respuesta a las posibles transiciones que puede realizar desde el estado actual.
Permítame ilustrar lo que HATEOAS se basa en mi comprensión, y corríjame si me perdí algo.
/
GET: {
"_links": {
"child": [
{ "href": "http://myapi.com/articles", "title": "articles" }
]
}
}
/articles?contains=HATEOAS
GET: {
"_items": [
{ "uri": "http://myapi.com/articles/0", "title": "Why Should I Care About HATEOAS?" },
{ "uri": "http://myapi.com/articles/1", "title": "HATEOAS: Problem or Solution?" }
],
"_links": {
"self": { "href": "http://myapi.com/articles", "title": "articles" },
"parent": { "href": "http://myapi.com/", "title": "home" }
}
}
POST: {
"title": "A New Article",
"body": "Article body",
"tags": [ "tag1", "tag2" ]
}
/articles/0
GET: {
"title": "Why Should I Care About HATEOAS?",
"body": "Blah blah blah"
"tags": [ "REST", "HATEOAS" ],
"_links": {
"self": { "href": "http://myapi.com/articles/0", "title": "article" },
"parent": { "href": "http://myapi.com/articles", "title": "articles" }
}
}
Se afirma que HATEOAS proporciona dos beneficios principales:
-
El servicio completo se puede detectar desde el URI raíz, la documentación ya no es necesaria.
-
El cliente se desacopla del servidor, que ahora puede cambiar la estructura de URI libremente. Esto elimina la necesidad de la versión API.
Pero en mi opinión, un servicio es mucho más que su estructura URI. Para usarlo de manera efectiva, también necesita saber:
- qué parámetros de consulta puede usar y sus posibles valores
- la estructura de JSON / XML / cualquier documento que necesite enviar en sus solicitudes POST / PATCH / etc
- la estructura de la respuesta enviada por el servidor
- los posibles errores que pueden ocurrir
- ...
En base a lo anterior, HATEOAS solo resuelve una pequeña fracción de los problemas de descubrimiento y acoplamiento. Aún debe documentar los cuatro aspectos anteriores y los clientes aún estarán fuertemente acoplados al servidor debido a ellos. Para evitar romper clientes, todavía necesita la versión de su API.
El único beneficio que proporciona es que puede cambiar su estructura de URL más o menos libremente (por cierto, lo que sucedió con el principio " Los URI geniales no cambian "?). ¿Mi entendimiento es correcto?