Últimamente he estado leyendo sobre Hypermedia como el motor del estado de la aplicación (HATEOAS), la restricción que se dice que hace que una API web sea "realmente RESTful". Se reduce básicamente a 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:
Se puede descubrir todo el servicio a partir del URI raíz, ya no se necesita documentación.
El cliente está desacoplado del servidor que ahora puede cambiar la estructura de URI libremente. Esto elimina la necesidad de versiones de 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
- ...
Basado en lo anterior, HATEOAS solo resuelve una pequeña fracción de los problemas de descubrimiento y acoplamiento. Todavía necesita documentar los cuatro aspectos anteriores y los clientes aún estarán fuertemente acoplados al servidor debido a ellos. Para evitar romper clientes, aún necesita versionar su API.
El único beneficio que proporciona es que puede cambiar su estructura de URL más o menos libremente (por cierto, ¿qué pasó con el principio "Los URI geniales no cambian" ?). ¿Es correcto mi entendimiento?