Lately I've been reading about Hypermedia as the Engine of Application State (HATEOAS), the constraint that is claimed to make a web API "truly RESTful". It boils down to basically including links with every response to the possible transitions you can make from the current state.
Let me illustrate what HATEOAS is based on my understanding - and please do correct me if I missed something.
/
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" }
}
}
HATEOAS is claimed to provide two major benefits:
The entire service is discoverable starting form the root URI, documentation is no longer needed.
The client is decoupled from the server which can now change the URI structure freely. This eliminates the need for API versioning.
But in my view, a service is a lot more than its URI structure. To use it effectively, you also need to know:
- what query parameters you can use and their possible values
- the structure of the JSON/XML/whatever documents you need to send in your POST/PATCH/etc requests
- the structure of the response sent by the server
- the possible errors that might occur
- ...
Based on the above, HATEOAS only solves a tiny fraction of the discoverability and coupling problems. You still need to document the above four aspects and clients will still be strongly coupled to the server because of them. To avoid breaking clients, you still need to version your API.
The only benefit it provides is that you can change your URL structure more or less freely (by the way, what happened to the principle "Cool URIs don't change"?). Is my understanding correct?