Build APIs You Won't Hate
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; the latter of 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:
- Content negotiation
- 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 also super easy to do.
1.2 Content Negotiation
Some self-proclaimed RESTful APIs (Twitter, you are to blame for this) handle content negotiation with file extensions. Their URLs often look like:
This is a bit of a misuse of the concept of a resource and forces users to know not only that the endpoint show exists, but that they must pick a content type extension and that the
id parameter must be used.
A good API would simply have
/statuses/210462857140252672. This has the dual benefit of letting the API respond with a default content type, or respecting the
Accept header and either outputting the request content type or spitting out a
415 status code if the API does not support it. The second benefit is that the consumer does not need to know about
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 response would then contain JSON if the API supports JSON as an output format.
Most popular APIs will support JSON by default, or maybe only JSON as our sample app has done so far. This is not realistic, but has been done throughout the book so far, mainly for the sake of simplicity.
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.
~/apisyouwonthate/chapter12/ for the updated sample app.
The main change other than including the Symfony YAML component was to simply update the
respondWithArray() method to check the
Accept header and react accordingly.
Very basic, but now if we try a different MIME type we can expect a different result:
The response will be in YAML.
Making these requests programmatically is simple.
This is not the end of the conversation for content negotiation as there is more to talk about with vendor-based MIME types for resources, which can also be versioned. To keep this chapter on point, that discussion will happen in Chapter 13: API Versioning.
1.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.
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. Roy Fielding says that without hypermedia controls an API is not RESTful, writing back in 2008. People have been ignoring that ever since, and the last estimate was that 74% of APIs claiming to be “RESTful” do not actually use hypermedia.
There is something floating around the REST/Hypermedia community called the Richardson Maturity Model, written about here by Martin Fowler but originally invented by Leonard Richardson. It covers what he considers to be ‘the four levels of REST’:
- “The Swamp of POX.” You’re using HTTP to make RPC calls. HTTP is only really used as a tunnel.
- 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.
- 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.
- Hypermedia Controls. HATEOAS. You’re 100% REST compliant.
– Source: Steve Klabnik, “Haters gonna HATEOAS”
Some dispute this model because, as Roy says, unless you have hypermedia then it is not REST. The model is good as long as you understand that steps 1, 2 and 3 are still “not REST” and step 4 is “REST”.
So, what are hypermedia controls? They are just links to other content, relationships, and further actions. These allow a consumer to browse around the API, discovering actions as it goes.
Basically, your data needs to have “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 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 general underlying theme of hypermedia 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 been sneakily sprinkled throughout this book, from suggesting error codes be combined with human readable error messages and documentation links, to helping the client application avoid maths 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 either 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 not to leave this section at “just add links mate” (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 to read the documentation and understand what data can be related, and to discover where that data might live. This is far from ideal.
To tie one
place to the related resources, subresources or collections is easy.
Here are three simple entries, with the first linking to itself. They all contain a
Resource Indicator) and a
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
place resource, you will have called
POST /places, and that is not what you would want to
call again to get updated information on the same resource. Regardless of the context, outputting a
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
As for the other
rel items, they are links to subresources that 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
checkins relationship (eg:
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 has been used as an example throughout the book - then you can simply do the following:
People try to get smarter and have various relationships based on their
$_SERVER settings or based
on 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. This then 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
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:
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
HTTP has us covered here with a simple and effective verb that has so far not been discussed:
By inspecting the
Allow header, we as humans (or programmatically as an API client application), can work
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
OPTIONS call just as easily as making a
POST call. If your HTTP client does not let you do
this, then change your HTTP client.
So in this instance, we know that we can get a list of check-ins 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
It might seem a little nuts to take 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 navigating 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. Compare 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 and 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 won’t 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.