Hypermedia as the engine of application state.  Wow, that’s a mouthful.  Many people shorten the phrase to HATEOAS, which is only slightly less of a mouthful (or keyboardful), but it’s what we’ve got.  HATEOAS is one of the core principles of the REST architectural style.  When the principle is followed correctly it provides several key benefits to a web service.

Let’s break the principle down, talk a little bit about why it’s important, and then we’ll get into the nuts and bolts of how to implement it in your web service.

What?

Hypermedia is really just a fancy word for a link.  It is an object that has within it pointers or links to other pieces of media, which could be text, images, audio or video.

We all know a link when we see one:

• You click on a picture of a movie poster and the trailer for that movie is played.
• You click the “Save” button for your order at an online bookstore and your order is processed.
• You select a phrase in Spanish and it is read aloud to you.

HATEOAS simply means that the client should be guided through your application using links.  This is not a new concept.  The web is built on this principle.  Without it the internet would have been an abysmal failure.  Because of HATEOAS, all I need to know to do my searching is google.com.  All I need to know to handle my finances is mint.com.  All I need to know to find a great place to work is bti360.com.  When a web application follows the HATEOAS principle, all I need to know to use it is the starting point and how to interpret the information displayed once I get there.

Why?

As we’ve said before, a web service is simply a web site designed to be consumed by machines instead of people.  So it makes sense that a web service can and should derive the same benefits from HATEOAS as all the web sites on the internet.  Those benefits are:

• Limited prior knowledge for clients to use the service.  They only need the starting point and the ability to interpret at least one of your services resource representations.
• Increased flexibility.  By limiting the client’s prior knowledge, it leaves many areas of your service implementation free to be changed when necessary.

How?

Ok, you’ve bought in to the whole HATEOAS principle and want to add it to your web service.  Let’s show you how to do just that.

I’m going to continue with a dictionary/thesaurus example that was begun in previous blogs.  So below we have a client request for a word in our dictionary, and the service response:

Client Request:

GET  /dictionary/happy HTTP/1.1
Accept:  text/xml

Service Response:

<?xml version="1.0" encoding="UTF-8"?>
<entry>
  <word>happy</word>
  <part-of-speech>adjective</part-of-speech>
  <definition>delighted, pleased, or glad, as over a particular thing</definition>
</entry>

So let’s say our service also provided synonyms.  In the above example there is no mention of synonyms for the word “happy”.  In that situation, the client would have to know ahead of time that our service provided synonyms, and what the URL was to retrieve the synonyms for the word “happy”.

Now let’s look at the same request, only this time the service is going to follow the HATEOAS principle:

Client Request:

GET  /dictionary/happy HTTP/1.1
Accept:  text/xml

Service Response:

<?xml version="1.0" encoding="UTF-8"?>
<entry>
  <word>happy</word>
  <part-of-speech>adjective</part-of-speech>
  <definition>delighted, pleased, or glad, as over a particular thing</definition>
  <link rel="synonyms" type="text/xml" uri="http://example.com/dictionary/happy/synonyms" />
  <link rel="antonyms" type="text/xml" uri="http://example.com/dictionary/happy/antonyms" />
</entry>

Now we’ve embedded in our entry a link to that word’s synonyms.  If the client understands our entry representation (including what the “synonyms” relationship means), and understands the data type for the synonyms link, then the synonyms can be retrieved simply by following this link.  It’s really that simple.

Wrap Up

Following the HATEOAS principle is important for any RESTful web service.