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)
HATEOAS RESTBucks https://www.infoq.com/articles/webber-rest-workflow
RESTBucks coffeeshop https://youtu.be/aQVSzMV8DWc?t=773
Wikipedia https://en.wikipedia.org/wiki/HATEOAS
O’Reilly https://www.oreilly.com/content/how-a-restful-api-represents-resources
Jobin Basani https://jobinbasani.com/2020/08/01/hypermedia-rest-api-using-spring-hateoas/
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)
Swedbank Pay https://developer.swedbankpay.com
PayPal https://developer.paypal.com/docs/api/reference/api-responses
Amazon https://docs.aws.amazon.com/apigateway/api-reference
GitHub Docs https://docs.github.com/en/rest/overview/resources-in-the-rest-api#hypermedia
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
Alternative overview https://github.com/evert/evert.github.com/blob/master/_posts/2021/2021-02-20-who-uses-hateoas.md
NOT Why HATEOAS does not work
Stackoverflow I https://stackoverflow.com/questions/65236613/restful-api-hateoas
Vinay Sahni https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#hateoas
Andreas Reiser https://medium.com/@andreasreiser94/why-hateoas-is-useless-and-what-that-means-for-rest-a65194471bc8
InterCoolerjs.org https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html
InfoQ https://www.infoq.com/news/2014/03/rest-at-odds-with-web-apis/
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?
Ben Morris https://www.ben-morris.com/pragmatic-rest-apis-without-hypermedia-and-hateoas
Tom Hombergs https://reflectoring.io/rest-hypermedia/

Leave a comment

Your email address will not be published. Required fields are marked *