11436 SSO

API Design: Honing in on HATEOAS

Brian Mulloy
Jun 17, 2013

We recently discussed the six constraints of REST but today we'll deepen our discussion of hypermedia as the engine of application state or HATEOAS (hay-dee-ous), in an attempt to understand what HATEOAS really means.

State Diagram

Here is a state diagram, which is essentially a directed graph with a series of nodes and arcs. Nodes represent states in the state machine, and arcs represent transitions. When traversing the state machine, you move through states via transitions. This has significance toward understanding REST, as exemplified in the following quote about experiencing REST in the real world:

“ The name ‘Representational State Transfer’ is intended to evoke an image of how a well-designed Web application behaves: a network of Web pages (a virtual state-machine), where the user progresses through the application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use.” ~Roy Fielding, Chapter 6, Architectural Styles and the Design of Network-based Software Architectures

On the state machine, states are Web pages and transitions are hyperlinks, so the key to implementing HATEOAS is quite simple: include links in responses that go from the server to the client.

In the example above, the app user is using a browser-based app, built by an app developer, that complies with the REST interface to accesses a UI server. The arrow on the top shows the browser request traversing the REST interface to the UI server. The arrow on the bottom shows the URL request response, including links (transitions) from one state of the state machine to the next.

Twitter Browser

Here is the Twitter UI in a browser with the first tweet. Notice the text “just setting up my twttr.” The UI includes choices (transitions) that allow the user to take action.

State Diagram: Twitter UI Node

This is the state diagram for the UI node in Twitter—arguably the simplest Web app ever built. For one tweet, there is one transition in and there are thirty-two transitions out from the Google state machine to the Twitter state machine.

The modest hyperlink may be one the greatest inventions ever created. However, it takes careful consideration to create seamless state transitions, which is why good Web API designers are sought after. With a browser, we are guided to effortlessly navigate our way through every state of an application. HATEOAS is the key constraint that makes surfing the Web possible.

HATEOAS in the context of APIs

Twitter API

GET /1/statuses/show/20.json
Host: api.twitter.com

The Twitter API looks very similar to the UI. An HTTP GET on a tweet transitions to api.twitter.com.

A JSON representation of the resource is returned. What’s familiar is the text coming from Twitter (via Jack Dorsey) but there are no hyperlinks. Without a way to transition from state to state, we end up hitting a dead end. Removing hyperlinks from a resource response is antithetical to HATEOAS.

How many links do we need to respect the HATEOAS constraint?

There needs to be at least one link. One obvious link is to the user, which creates a state transition for the API client.


This completes our review of the six constraints of REST.

To join the conversation around APIs, check out the API Craft Google Group and the IRC Channel #api-craft on freenode.

For further reading, see:

A special thanks to the api-craft community, who helped pull this content together.

Next: API Design: Harnessing HATEOAS, Part 1

Scaling Microservices