Blueprint Forge.

Building things with computers.

A Short Explanation of Hypermedia Controls in RESTful Services

This article roughly follows on from my previous post on REST, which discusses some points relating to the first two levels of the Richardson Maturity Model. Since we’re only going to discuss the top level of the model in this post (shown below), the other levels are greyed out.

Diagram of the Richardson Maturity Model showing three elements of RESTful services: resources, http verbs and hypermedia controls

Introducing Hypermedia Controls

Hypermedia as the Engine of Application State (HATEOAS) is an element of the REST architectural style, which describes how a consumer can control a given web application using hypermedia controls.

Let’s cut straight to the chase: what do we mean by hypermedia controls?

When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions… Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types. –Roy Fielding

This explanation, from Roy Fielding’s widely cited blog post REST APIs must be Hypertext driven mentions the “simultaneous presentation of information and controls”. To simplify, we can imagine a hyperlink that our consumer is able to understand and manipulate.

So that’s the first word of HATEOAS. What does “Engine of Application State” mean? Quite literally, it means that the hyperlinks mentioned above can be used to control (drive) the web application. If you haven’t already drawn a state machine for your application, now’s the time!

Take, for instance, a RESTful webservice that allows virtual machines to be controlled. The Sun Cloud API is one example of such a service – the examples below are based loosely on the format it uses. If a given virtual machine is stopped, it be may started. Or, if a machine is already running, it may be stopped.

Example request for a machine representation:

1
2
3
GET /machines/1/
Host: example.com
Accept: application/xml

Example response:

1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/xml
<status>stopped</status>
<link rel="start" method="post" href="machines/2?op=start" />

Note the link tag. This is a hypermedia control which tells the consumer how it could start the VM by POSTing to machines/{id}?op=start. (For simplicity I’ve omitted necessary details such as Content-Length and xml schema declaration.)

If the requested VM is running, the response would be:

1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/xml
<status>running</status>
<link rel="stop" method="post" href="machines/2?op=stop" />

When our VM is running, the resource at machines/1/ contains a rel link to stop it. Both methods would probably return 201 Accepted in the case of success, as it is unlikely they would run synchronously.

In a nutshell, this is the concept of HATEOAS – these hypermedia resources allow us to control application state.

Note that the operation type in the query parameter could also have been a separate resource (such as machines/1/stop). There are arguments for either approach but it isn’t necessary to delve into this to understand the concept of HATEOAS.

Why Hypermedia Controls are Important

In the example above, the representation of a resource also gives us a way to manipulate the resource. In this way, HATEOAS allows certain aspects of the application to be self-describing, fostering loose coupling between service and consumer. If we consider that a service may evolve over time, then this loose coupling could allow the client to evolve with fewer issues than if all controls were hard-coded.

A useful resource that covers this in more detail is Wayne Lee’s presentation Why HATEOAS. Craig McClanahan also discusses the benefits of HATEOAS for service discovery and integration.

This post has necessarily glossed over many details of how HATEOAS is implemented, but has hopefully served as a useful introduction to the notion. I recommend REST in Practice as a resource for going into the subject in more detail. Additionally, the RESTful Services Cookbook contains details on implementation.

Further sources:

  1. Roy Fielding: Rest APIs must be Hypermedia Driven
  2. Ian Bicking on Hypertext Driven URLs
  3. REST and HATEOAS
  4. Interesting Stack Overflow discussion