HATEOAS - Build APIs You Won't Hate: Everyone and their dog wants an API, so you should probably learn how to build them (2014)

Build APIs You Won't Hate: Everyone and their dog wants an API, so you should probably learn how to build them (2014)


12.1 Introduction

HATEOAS is a tricky subject to explain, but it is actually rather simple. It stands for “Hypermedia as the Engine of Application State”, and is pronounced as either “hat-ee-os”, “hate O-A-S” or “hate-ee-ohs” - which sounds a little like a cereal for API developers.

However you want to try and say it, it basically means two things for your API:

1. Content negotiation

2. Hypermedia controls

In my experience content negotiation is one of the first things many API developers implement. When building my CodeIgniter Rest-Server extension it was the first feature I added, because hey - it is fun! Changing the Accept header and seeing the Content-Type header in the response switch from JSON to XML or CSV is great, and is super easy to do.

12.2 Content Negotiation

Some self proclaimed RESTful APIs (Twitter, I blame you for this) handle content negotiation with file extensions. They do things like /statuses/show.json?id=210462857140252672 and /statuses/show.xml?id=210462857140252672 instead of just /statuses/210462857140252672 and letting theAccept header do the work.

URIs are not supposed to be a bunch of folders and file names, and an API is not a list of JSON files or XML files. They are a list of resources that can be represented in different formats depending on the Accept header, and nothing else.

A simple example of proper RESTful content negotiation requesting JSON

1 GET /places HTTP/1.1

2 Host: localhost:8000

3 Accept: application/json

A response would then contain JSON, if the API supports JSON as an output format.

A shortened example of the HTTP response with JSON data

1 HTTP/1.1 200 OK

2 Host: localhost:8000

3 Connection: close


5 {

6 "data": [

7 {

8 "id": 1,

9 "name": "Mireille Rodriguez",

10 "lat": -84.147236,

11 "lon": 49.254065,

12 "address1": "12106 Omari Wells Apt. 801",

13 "address2": "",

14 "city": "East Romanberg",

15 "state": "VT",

16 "zip": 20129,

17 "website": "http://www.torpdibbert.com/",

18 "phone": "(029)331-0729x4259"

19 },

20 ...

21 ]

22 }

Many RESTful APIs will support JSON by default, or maybe only JSON as our sample app has done so far. This is not realistic, but was done mainly for the sake of simplicity throughout the book so far.

XML is still a tricky one to do as you need to require view files, and that is out of scope of this chapter.

YAML however is rather easy to achieve, so we can see how content negotiation works with a little change to our app. Check ~/apisyouwonthate/chapter12/ for the updated sample app.

The main change other than including the Symfony YAML component was to simply update the ApiController::respondWithArray() method to check the Accept header and react accordingly.

1 protectedfunction respondWithArray(array $array, array $headers = [])

2 {

3 // You will probably want to do something intelligent with charset if provided.

4 // This chapter just ignores everything and takes the main mime-type value


6 $mimeParts = (array) explode(';', Input::server('HTTP_ACCEPT'));

7 $mimeType = strtolower($mimeParts[0]);


9 switch ($mimeType) {

10 case 'application/json':

11 $contentType = 'application/json';

12 $content = json_encode($array);

13 break;


15 case 'application/x-yaml':

16 $contentType = 'application/x-yaml';

17 $dumper = new YamlDumper();

18 $content = $dumper->dump($array, 2);

19 break;


21 default:

22 $contentType = 'application/json';

23 $content = json_encode([

24 'error' => [

25 'code' => static::CODE_INVALID_MIME_TYPE,

26 'http_code' => 415,

27 'message' => sprintf('Content of type %s is not supported.', $mimeType\

28 ),

29 ]

30 ]);

31 }


33 $response = Response::make($content, $this->statusCode, $headers);

34 $response->header('Content-Type', $contentType);


36 return $response;

37 }

Very basic, but now if we try a different mime-type we can expect a different result:

A HTTP request specifying the preferred response mime-type

1 GET /places HTTP/1.1

2 Host: localhost:8000

3 Accept: application/x-yaml

The response will be in YAML.

A shortened example of the HTTP response with YAML data

1 HTTP/1.1 200 OK

2 Host: localhost:8000

3 Connection: close


5 data:

6 - { id: 1, name: 'Mireille Rodriguez', lat: -84.147236, lon: 49.254065, address1: '121\

7 06 Omari Wells Apt. 801', address2: '', city: 'East Romanberg', state: VT, zip: 20129, web\

8 site: 'http://www.torpdibbert.com/', phone: (029)331-0729x4259 }

9 ...

Making these requests programmatically is simple.

Using PHP and the Guzzle package to request a different response type

1 use GuzzleHttp\Client;


3 $client = new Client(['base_url' => 'http://localhost:8000']);


5 $response = $client->get('/places', [

6 'headers' => ['Accept' => 'application/x-yaml']

7 ]);


9 $response->getBody(); // YAML, ready to be parsed

This is not the end of the conversation for content negotiation, as there is a little bit more to talk about with vendor-based mime-types for resources, which can be versioned too. To keep this chapter on point, that discussion will happen in Chapter 13: API Versioning.

12.3 Hypermedia Controls

The second part of HATEOAS however is drastically underused, and is the last step in making your API technically a RESTful API.

Batman provides a standard response to often futile bucket remark "But it's not RESTful if you..." Credit to Troy Hunt (@troyhunt)

Batman provides a standard response to often futile bucket remark “But it’s not RESTful if you…” Credit to Troy Hunt (@troyhunt)

While you often hear complaints like “but that is not RESTful!” from people about silly things, this is one instance where they are completely right. Without hypermedia controls you just have an API, not a RESTful API. This is an aspect in which 99% of all APIs fall short.

RESTful Nirvana

1. “The Swamp of POX.” You’re using HTTP to make RPC calls. HTTP is only really used as a tunnel.

2. Resources. Rather than making every call to a service endpoint, you have multiple endpoints that are used to represent resources, and you’re talking to them. This is the very beginnings of supporting REST.

3. HTTP Verbs. This is the level that something like Rails gives you out of the box: You interact with these Resources using HTTP verbs, rather than always using POST.

4. Hypermedia Controls. HATEOAS. You’re 100% REST compliant.
– **Source: ** Steve Klabnik, “Haters gonna HATEOAS”

That article is based off an article by Martin Fowler called “Richardson Maturity Model” and explains a model written by Leonard Richardson covering what he considers to be the four levels of REST maturity.

So what are hypermedia controls? They are just links, a.k.a “Hyperlinks”, which you have probably been using in your HTML output for years. I said early on in the book that REST is just using HTTP and the same conventions as the actual internet instead of inventing new ones, so it makes sense that linking to other resources should be the same in an API as it is in a web page.

The underlying theme of HATEOAS in general is that an API should be able to make perfect sense to an API client application and the human looking at the responses, entirely without having to hunt through documentation to work out what is going on.

Small HATEOAS concepts have sneakily been sprinkled throughout this book, from suggesting error codes be combined with human readable error messages and documentation links, to helping the client application avoid math when interacting with pagination. The underlying theme is always to make controls such as next, previous or any other sort of related interaction clearly obvious to a human or a computer.

Understanding Hypermedia Controls

This is the easiest part of building a RESTful API, so I am going to try really hard to not just leave this section at: “Just add links mate.” - which is my normal advice for anyone asking about HATEOAS.

Our usual data is output in such a way that only represents one or more resources. By itself, this one piece of data is an island, completely cut off from the rest of the API. The only way to continue interacting with the API is for the developer has read the documentation and understands what data can be related, and discover where that data might live. This is far from ideal.

To tie one place to the related resources, sub-resources or collections is easy.

1 {

2 "data": [

3 "id": 1,

4 "name": "Mireille Rodriguez",

5 "lat": -84.147236,

6 "lon": 49.254065,

7 "address1": "12106 Omari Wells Apt. 801",

8 "address2": "",

9 "city": "East Romanberg",

10 "state": "VT",

11 "zip": 20129,

12 "website": "http://www.torpdibbert.com/",

13 "phone": "(029)331-0729x4259",

14 "links": [

15 {

16 "rel": "self",

17 "uri": "/places/2"

18 },

19 {

20 "rel": "place.checkins",

21 "uri": "/places/2/checkins"

22 },

23 {

24 "rel": "place.image",

25 "uri": "/places/2/image"

26 }

27 ]

28 ]

29 }

Here are three simple entries, with the first is linking to itself. They all contain a uri (Unviversal Resource Indicator) and a rel (Relationship).



The acronym “URI” is often used to refer to only content after the protocol, hostname and port (meaning URI is the path, extension and query string), whilst “URL” is used to describe the full address. While this is not strictly true, it is perpetuated by many software projects such as CodeIgniter. Wikipedia and the W3 say a bunch of conflicting things, but I feel like a URI is easily described as being simply any sort of identifier for the location of a resource on the internet.

A URI can be partial, or absolute. URL is considered by some to be a completely non-existant term, but this book uses URL to describe an absolute URI, which is what you see in the address bar. Rightly or wrongly. Got it?

Some people scoff at the self relationship suggesting that it is pointless. While you certainly know what URL you just called, that URL is not always going to match up with the self URI. For example, if you just created a place resource you will have called POST /places, and that is not a what you would want to call again to get updated information on the same resource. Regardless of the context, outputting a place always needs to have a self relationship, and that self should not just output whatever is in the address bar. Basically put, the self relationship points to where the resource lives, not the current address.

As for the other rel items, they are links to sub-resources which contain related information. The content of the tags can be anything you like, just keep it consistent throughout. The convention used in this example is to namespace relationships so that they are unique. Two different types of resources could have a checkins relationship (eg: users and places) so keeping them unique could be of benefit for the sake of documentation at least. Maybe you would prefer to remove the namespace, but that is up to you.

Those custom relationships have fairly unique names, but for more generic relationships you can consider using the Registry of Link Relations defined by the IANA, which is used by Atom (RFC 4287) and plenty of other things.

Creating Hypermedia Controls

This is literally a case of shoving some links into your data output. However you chose to do that, it can be part of your “transformation” or “presentation” layer.

If you are using the PHP component Fractal - which we has been used as an example throughout the book - then you can simply do the following:

PlaceTransformer with links included in the response data.

1 publicfunction transform(Place $place)

2 {

3 return [

4 'id' => (int) $place->id,

5 'name' => $place->name,

6 'lat' => (float) $place->lat,

7 'lon' => (float) $place->lon,

8 'address1' => $place->address1,

9 'address2' => $place->address2,

10 'city' => $place->city,

11 'state' => $place->state,

12 'zip' => (float) $place->zip,

13 'website' => $place->website,

14 'phone' => $place->phone,


16 'links' => [

17 [

18 'rel' => 'self',

19 'uri' => '/places/'.$place->id,

20 ],

21 [

22 'rel' => 'place.checkins',

23 'uri' => '/places/'.$place->id.'/checkins',

24 ],

25 [

26 'rel' => 'place.image',

27 'uri' => '/places/'.$place->id.'/image',

28 ]

29 ],

30 ];

31 }

People try to get smarter and have various relationships based off of their $_SERVER settings or based off of their ORM relationships, but all of that is just going to cause you problems. If you have these transformers then you only need to write this lot out once and it avoids exposing any database logic and keeps your code readable and understandable.

Once you have input these links, other people need to know how to interact with them. You might think “Surely I should put GET or PUT in there so people know what to do?” Wrong. They are links to resources, not actions. An image exists for a place, and we can either blindly assume we can make certain actions on it, or we can ask our API what actions are available and cache the result.

Discovering Resources Programmatically

Taking a shortened example from earlier on in this chapter, we can expect to see output like this:

1 {

2 "data": [

3 ...

4 "links": [

5 {

6 "rel": "self",

7 "uri": "/places/2"

8 },

9 {

10 "rel": "place.checkins",

11 "uri": "/places/2/checkins"

12 },

13 {

14 "rel": "place.image",

15 "uri": "/places/2/image"

16 }

17 ]

18 ]

19 }

We can assume that a GET will work on both the self and the place.checkins endpoints, but what else can we do with them? Beyond that, what on Earth do we do with the place.image endpoint?

HTTP has us covered here, with a simple and effective verb that so far has not discussed: OPTIONS.

A HTTP request using the OPTIONS verb

1 OPTIONS /places/2/checkins HTTP/1.1

2 Host: localhost:8000

The response to the previous HTTP request

1 HTTP/1.1 200 OK

2 Host: localhost:8000

3 Connection: close


By inspecting the Allow header, we as humans (or programmatically as an API client application) can work out what options are available to us on any given endpoint. This is what JavaScript is often doing in your browser for AJAX requests and you might not even know it.

Doing this programmatically is pretty easy too, and most HTTP clients in any given language will let you make an OPTIONS call just as easily as making a GET or POST call. If your HTTP client does not let you do this, then change your HTTP client.

Making an OPTIONS HTTP request using PHP and the Guzzle package

1 use GuzzleHttp\Client;


3 $client = new Client(['base_url' => 'http://localhost:8000']);

4 $response = $client->options('/places/2/checkins');

5 $methods = array_walk('trim', explode(',', $response->getHeader('Accept'));

6 var_dump($methods); // Outputs: ['GET', 'HEAD', 'POST']

So in this instance we know that we can get a list of checkins for a place using GET, and we can add to them by making a POST HTTP request to that URL. We can also do a HEAD check, which is the same as a GET but skips the HTTP body. You will probably need to handle this differently in your application, but this is handy for checking if a resource or collection exists without having to download the entire body content (i.e: just look for a 200 or a 404).

It might seem a little nuts to go to this extra step to interact with an API, but really it should be considered much easier than hunting for documentation. Think about it, trying to find that little “Developers” link on the website, then navigate to the documentation for the correct API (because they are so cool they have about three), then wondering if you have the right version… not fun. Compared that to a programmatically self-documenting API, which can grow, change and expand over time, rename URLs and… well that is a real win. Trust me.

If you know that an API follows RESTful principles then you should be confident that it follows HATEOAS - because advertising it as RESTful without following HATEOAS is a big stinking lie. Sadly, most of the popular APIs out there are big stinking liars.

GitHub responds with a 500, Reddit with 501 Not Implemented, Google maps with 405 Method Not Allowed. You get the idea. I’ve tried many others, and the results are usually similar. Sometimes it yields something identical to a GET response. None of these are right.
Source: Zac Stewart, “The HTTP OPTIONS method and potential for self-describing RESTful APIs”

If you are building your own API then you can easily do this yourself, then your clients know that you know how to build a decent API.

And that, is about all there is for HATEOAS. You should now know enough to go out and build up an API that in theory you wont hate. Sadly, you will probably need to build a new version within a few months regardless, so for that we will now take a look at API versioning.