With HATEOAS (Hypermedia As The Engine Of Application State) clients are able to handle control logic in discovering the APIs. It is a constraint on REST that says that ideally, the client has to know just one single root URI entrypoint, everything else should be discoverable dynamically from that URI through hyperlinks included in the representations of returned resources.
A webpage is an instance of application state; hypermedia is text with hyperlinks. The hypermedia drives (i.e. acts as an engine of) the application state. In other words it just means that we click on links to move to new pages (i.e. switching between application states). So when you are surfing the web, you are using HATEOAS!
According to HATEOAS all APIs are self-descriptive (like websites) and all actions which can be performed on resources are described in the representations of resources in the form of annotated links. The API should guide the client to the next application state by using hypermedia – media with links – in the API response. Asking for clients to build URLs is the opposite of the HATEOAS principle. The API is the engine of application state, since it’s driving the client to the possible ways of changing the application state.
Roy Fielding is very explicit about the use of hypermedia, not in his thesis, but the more in his blog:
In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period.
and in the following interview:
…”hypermedia as the engine of application state” is a REST constraint. Not an option. Not an ideal. Hypermedia is a constraint. As in, you either do it or you aren’t doing REST.
HATEOAS is one of the most important constraints, unique to the REST stipulation, but also the least understood. It seems to divide the RESTafarians into different camps. The links below will provide you further information. Are you getting hyper about hypermedia APIs?
|Functionality||How HATEOAS works|
|Nordic APIs I||https://youtu.be/QIv9YR1bMwY?t=948|
|Nordic APIs II||https://nordicapis.com/wp-content/uploads/API-Design-on-the-scale-of-Decades.pdf (p.8)|
|HOT||Why HATEOAS works|
|Asjborn Ulsberg||https://nordicapis.com/rest-state-machine-revisited/ (Nordic APIs)|
|Spencer Russel||https://dl.acm.org/doi/10.4108/icst.mobiquitous.2014.258072 (Hypermedia APIs and IoT)|
|Foxy Hypermedia API||https://api.foxycart.com/docs|
|VISA Payments Processing||https://developer.visa.com/capabilities/vpp/docs-how-to|
|Microsoft API implementation||https://docs.microsoft.com/nl-nl/azure/architecture/best-practices/api-implementation|
|NOT||Why HATEOAS does not work|
|Pakal de Bonchamp||https://www.freecodecamp.org/news/follow-up-to-rest-is-the-new-soap-the-origins-of-rest-21c59d243438/|
|Pragmatic||Should we care?|