I will close this article by addressing some dangling criticisms of HATEOAS.
HATEOAS is not about eliminating external documentation and embedding said documentation into the the responses served.
This would be like saying writing self-describing code over having extensive code comments has the end-goal of making documentation obselete. Even with self-describing class names, methods and comprehensive tests, you will still need external documentation to tell users how to use the system for different use cases. Self-describing code reveals intent, is easier to understand and change; self-describing API responses reduce the cognitive overhead of interpreting the data and reveal the relationship between different resources without directly coupling their data.
There are generally two different kinds of documentation:
- Documentation which communicates to the developer(s) why certain design decisions were made, so that in the future it is easier to make changes to the codebase.
- Documentation which is for the consumer of the API, which is not meant to explain the design decisions or reveal implementation details, but to make the API as easy as possible to use.
HATEOAS helps with (1), but has only partial effects on (2).
HATEOAS is not a silver bullet for versioning your API, nor is it intended to be.
So if you decide to add, rename or remove properties to/from your API responses, the consumers of your API will need to know whether or not the changes will break their current integrations. This is unavoidable. The changes within the API can be minimized by the fact that you’re referencing resources, so the changes will be on the resources themselves: but the changes ultimately need to be communicated to your consumers.
HATEOAS doesn’t require concensus over naming standards in order to be useful: simply a situation where resources are better served as external references instead of embedded content.
It doesn’t matter whether you decide to name your properties using
_link, or adopt HAL or the JSON API spec or anything else. These are conventions designed to align with how HTML hyperlinks are designed, but every REST API will require clients to understand particular aspects of the responses (e.g. knowing that they are hitting a product catalog service, and hence that they need to find a
product_id in the response body). It is fine for you to use your own convention: so long as you keep it consistent within your own API, easy to understand and easy to consume.