Ú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?
Lo único que lo convierte en una verdadera API REST es cumplir con todas las restricciones, no solo una.
Es por eso que necesitamos otras restricciones, mensajes autodescriptivos, etc.
No importa cómo lo intentes, necesitarás versionar tu API. En un cliente REST, aún necesita saber cómo llegar a una página donde desea hacer cosas, qué enlaces seguir y qué propiedades debe recopilar en función del vocabulario RDF que describe el mensaje. Si necesita reemplazar o eliminar algo de ese vocabulario, probablemente romperá a todos sus clientes y necesitará una nueva versión. Así que creo que REST no es algo que debas publicar antes (y descifrar el modelo mientras cambias constantemente la API), de lo contrario tendrás muchas versiones. Primero necesita un modelo de dominio estable en el que pueda construir ...
fuente