I’ve spent a fair amount of time both authoring and consuming RESTful APIs that adhere to the HATEOAS constraint that has become so popular lately. An acronym for Hypertext as the Engine of Application State, it typically means that the API provides hypertext links for clients to navigate their structure. Unfortunately I don’t think this serves the purpose that it was intended to serve, and ultimately impedes development of both services and clients.
The fundamental problem with HATEOAS is that it requires that the consumer either know or be able to reason about the structure of the API. Without either of those, links are useless. The former is strictly an inconvenience compared to effective documentation (which can be generated automatically) and the latter is an unreasonable expectation, especially when the interface is consumed by an independent party who could not possibly know or anticipate changes to the API that have the potential to break the client’s ability to navigate or consume it.
It’s possible that links can follow established community conventions or standards such as HAL+JSON, somewhat mitigating the requirement to independently document the intended contents of links, but:
- This is not a requirement of REST, and
- Conventions could as easily be established as an independent standard not involving hypertext.
I don’t know that I have much more to say on the subject, but in conclusion — I’m inclined to provide effective, up-to-date documentation, preferably generated automatically by CI processes, in lieu of expecting clients to read and understand embedded hyperlinks.