HATEOAS

To understand HATEOAS (Hypermedia as the Engine of Application State), let's first take a look at how a client application interacts with an API without HATEOAS.

Let's say there is a client application that needs to consume an API to create new Sales Leads within a CRM application.

In order for the client to consume the API to create a new Sales Lead, the client must know in advance how the API contract is structured. From this the client can learn how to invoke the API, the request payload to send and the response to expect (1). The client can then implement the code changes on their side to consume the API (2 and 3) and a response is then returned back to the client (4).

If the client now wants to consume another API to get a particular Sales Lead, the process must be repeated.

Important thing to understand here is that the client needs to know in advance how the API contract is structured.

Now let's take a look at how a client application interacts with an API with HATEOAS.

When the client consumes an API, the response returns a list of actions that are possible on that API. Going back to our API to create new Sales Leads, when the client consumes the API (1), the response returns a bunch of links that tell the consumer possible things that can be done with that resource (2). In this case the client can either get the Sales Lead's details or delete the Sales Lead.

Using this approach allows clients to use the links returned in the response to drive what is possible on the API without knowing how the API contract is structured in advance. This is the problem that HATEOAS solves.