11436 SSO

API Design: Harnessing HATEOAS, Part 1

Brian Mulloy
Jun 20, 2013

Previously, we discussed HATEOAS (the hypermedia constraint) within the context of REST. This laid the groundwork for our discussion today, which is how to apply HATEOAS to an API strategy. Now, let’s look at some questions people have in regard to HATEOAS when setting up their API.

  • What does it mean to be compliant with HATEOAS?

  • Does adding new links to the API change an API client app’s state machine?

  • Does a developer, who ignores links pushed out though the API in their response, violate the hypermedia constraint?

  • Can developers add out-of-band links to state machine transitions?

  • What happens to the state machine when an app relies on multiple APIs? For example, if I create an app that uses Twitter’s API to link to Facebook’s API, who is responsible for the state machine?

  • Do app designers, who follow the hypermedia constraint, determine the user actions, or are these decisions driven by the links in the response from an API?

These questions typify the confusion and careful consideration that surround the hypermedia constraint debate. To try to add some clarity, here is what we know for sure:

Most of the popular Web UIs adhere to the hypermedia constraint of REST (HATEOAS), but many popular Web APIs do not.

Why is this? Let’s examine these two worlds.

In the world that adheres to the hypermedia constraint, the app developer crafts the interface (the state diagram), the REST interface guarantees HATEOAS, and the app user decides which link to click to initiate the state transition from the state machine.

Interestingly, the hypermedia links are given directly to the app user at runtime when they cross over that REST interface. This means the hypermedia link in each response acts as the engine of application state, unless the user hacks the URL in the browser address bar.

This pattern is not limited to a user interface through which an app developer crafts the user experience. We see the same pattern for syndication feeds through XML standards like AtomPub and RSS, where XML is the representation of the resource going across the REST interface.

In this example, a content publisher publishes content via stories, categories, and related media, while the REST interface still guarantees HATEOAS. The app user, using some kind of feed reader, decides which link to click to change state. But things can get tricky because the world of apps and Web APIs seem different.

In this example, we see an API server is available to multiple app developers, who create apps for app users. The app user decides where to click and change the state. This is significant because various app developers can create various user experiences, which means the app developers create different state diagrams. The app developer and the app user are no longer separated by a RESTful interface. The ensuing interface struggles to adhere to the HATEOAS constraint. The hypermedia links are not given directly to the app user at runtime; instead, they are given to the app developer at design time. The app developer then decides which of the links (state transitions) go to the app user at runtime. The significance is that we switch from a direct to an indirect way to change states.

This is the point in the conversation where people usually panic. So let’s step back and reframe the conversation using one of my favorite quotes from Star Wars.

You must unlearn what you have learned.” ~Yoda

At one point, I referred to popular Web APIs, which weren't HATEOAS or SOAP compliant, as pragmatic RESTful APIs. But I've changed my stance and have come to believe that HATEOAS is critical to making something truly RESTful. That is, Web APIs that are not HATEOAS compliant are by definition not RESTful.

A special thanks to the API Craft Google Group, who helped pull this content together. To join the conversation around APIs, check out the API Craft Google Group and the IRC Channel #api-craft on freenode. We'd love to get your feedback and perspective.

Next: API Design: Harnessing HATEOAS, Part 2

For further reading, see:

Scaling Microservices