HATEOAS: concise description

Question

I am trying to get a clear and concise understanding of HATEOAS, and I am by no means an expert WRT REST. (I think I get it though, thanks to this http://www.looah.com/source/view/2284 ).

Can anyone suggest an equally enlighenting blog/article WRT HATEOAS?

Answer 1

The Hypermedia Constraint (formerly known as HATEOAS) is a constraint that is used to provide direction to the user-agent.

By including links in returned representations, the server can remove the burden from the user-agent of determining what actions can be taken based on the current application state and knowing who to interact with in-order to achieve that goal.

As the server has no knowledge of the user-agent's current state other than what it receives in a request, it is important that the user-agent tries to avoid using state other than the representations returned from the server. This ensures that the available actions provided by the server are based the most complete understanding of the user-agent state as possible.

A user-agent conforming to the Hypermedia constraint acts like a state machine, where state transitions are caused by following links available in the current representation. The returned representation becomes the new state.

The benefits of this approach can be a very lightweight user-agent. It requires very little code to manage state as its actions should be based purely on the received response and the link that retrieved that response. The user agent code becomes declarative and reactive, rather than imperative sequences of GET this then do this and then do that, you simply have the mechanics for following links and many instances of WHEN you receive this THEN do that.

For an example of how this works, you need look no further than your web browser and a web site that doesn't use Javascript. The browser presents you with options based on links in the HTML. When you follow that link, the browser replaces its current state with the new state retrieved when you followed the link. The back button works (or at least should) because you are retrieving the state from a link in your history. The browser should not care how you got to the page, as the state should be based entirely on the retrieved representation.

This "state management" model can be very limiting, as your current application state is based on a single server response. However, complex applications can be built by using a set of user-agents working together. This is part of what AJAX achieves in that it allows a distinct user-agent to be used to make separate requests and therefore, in effect, manage another state machine. Unfortunately, most of the time people resort back to an RPC style when they start making javascript requests, which is unfortunate considering the natural asynchrony of Javascript.

Answer 2

HATEOAS in few words: In the data you output, refer to other resources using URIs, not IDs.

As all the short definitions, the definition I just gave is wrong on many levels, but it should make you understand what the crux of HATEOAS is.

Now, for a bit longer explaination.

The HATEOAS principle says that the state of your application should advance through hypertext links. Think of you browsing around the internet. First you have to type an address in the address bar. From that point on, your navigation advances pretty much only thanks to clicks on links: you click on a link and you end up on another page. Another click and here appears another page. How was the browser able to move you from the first page to the second to the third? It used the URLs encoded in <a> elements.

Similarly if your REST applications generates this result

<accomodation>
  <hotel info="http://example/hotel/0928374" price="200"/>
  <guest-house info="http://example/guest-h/7082" price="87"/>
</accomodation>

then the receiving application will not have to access any external sources of knowledge to know that the first hotel is available at http://example/hotel/0928374 and the second one at http://example/guest-h/7082.

On the other hand, if your application generates responses with IDs like

<accomodation>
  <hotel id="0928374" price="200"/>
  <guest-house id="7082" price="87"/>
</accomodation>

the receiving application will have to know in advance how IDs must be composed with prefixes to get the URI at which the information for each accommodation is available (for example "add http://example/ to every request, then add hotel for hotels and guest-h for guest houses"). You can see that this mechanism is similar to what happens in many DB applications but is different from how browsers work.

It is important to follow the HATEOAS principle because it allows applications to grow without drastic changes to the receiving applications. Suppose you want to change your URIs from http://example.com/hotel/0928374 to https://reviews.example.com/accommodation/0928374. If you followed HATEOAS is would be a simple change: modify the returned values and that it is: receiving applications will continue to work without any modification. If instead you had separate documentation for how to construct URI, you will have to contact all the application developers and ask them to notice that the documentation has been updated and they should change their code to reflect the changes.

Disclaimer: this is a quick answer that just scratches the surface of the problem. But if you get this you got 80% of the HATEOAS principle.