What is HATEOAS and why is it important for REST API?
Basically, my understanding on this is , A logic on the server side might change independently of the clients. With HATEOAS, these and
similar future changes have to be implemented on the server only, while the client remains oblivious to these decisions. I.e.,
one change on the server, and thousands or millions of clients can use the new feature without updating their application.
If your client understands HATEOAS, it can navigate your web application without knowing ahead of time what resources and actions your server provides. That means that if you build your client-side in such a way that it incorporates HATEOAS principles, you can indeed change your REST API or availability of certain resources on the fly, and the client applications won't break.
A good way to get to grips with HATEOAS is to take a look at how Paypal.com uses it. Their developer website has excellent documentation on how to use their REST API which includes HATEOAS.
Let's look at an example:
The Orders API is used to create orders: https://developer.paypal.com/docs/api/orders/. The API documentation shows that to create an order you have to POST a JSON representation of the order to the URI /v1/checkout/orders. The document gives an example POST request (on the right with black background). If you scroll down, you will see an example response from Paypal to a create order request. The response includes a confirmation of the order's details and, at the bottom of the JSON response, HATEOAS data. It looks like this:
HATEOAS data is always an array of links to other resources that are relevant to the resource requested/created. Here you can see that there are 3 links which have three elements: the URL of a REST endpoint, the 'name' of the REST endpoint, and the HTTP method you must use when making a request to that REST endpoint.
In most cases, you will always see a 'self' link which points back to the resource requested/created. Then, in this case, you have two other links. One link, that when called, approves the order and one that will cancel the order.
The frontend application, assuming that it's a web application, will read the HATEOAS endpoint links and use them when it generates a webpage. So the delete URL will be attached to the DELETE ORDER button and the approval URL will be attached to the APPROVE ORDER button. This is just one scenario and it is not required that the HATEOAS links are used, they can be ignored. However, the benefit is that the frontend application does not have to hardcode links to important functions. This frees the backend to change the link and the frontend application does not need to be refactored. For example, the delete link could be changed from version 1 to version 5 and would look like this: "https://api.paypal.com/v5/checkout/orders/8RU61172JS455403V" and the frontend would not need to be refactored to account for the change to the link.
This is just a quick introduction to HATEOAS and there is much more to be said about this topic but I hope this has given you a little taste.