Unconfuse yourself about REST, HATEOAS, and API design

I set out to create a simple REST API about a week ago. Having got a basic proof of concept working, I thought I’d look up the accepted wisdom on API design. Well! After a couple of days hacking through the seething jungle of opinion, holy wars and plain misinformation, I now realize it might be a little too soon for “accepted”. However, there were three things I found after much labour that really helped clarify my thinking, so I thought I’d call those out here.

Roy Fielding’s semi-rant on the hypermedia constraint


This article opened my eyes to the larger issues that REST was originally designed to address. It also is a handy test – if, like me, you find that much of the terminology in this article is unfamiliar, that’s a good sign that you haven’t really engaged with the work that’s been done on those issues. Knowing what you don’t know is always a good thing.

There’s a lot of nonsense not particularly useful stuff out there in the blogosphere about API discoverability, with the proponents struggling to come up with a really convincing benefit, and the opponents holding up the chimera of completely automated discoverability by a completely generic automaton as a kind of reductio ad absurdum. Fielding makes it clear that, while the automaton might be nice if you can afford to build it, a discoverable API is just as important for that most ubiquitous of generic user agents, the next generation of application programmers.

“REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution.” – Roy Fielding, comment #8

What’s a media type and how do you create one?

Two things become clear in the comment stream from the above article (and other sources):

  1. Fielding sees “out-of-band” information (that is, the stuff that the parties in a client-server interaction have to know that is not contained within the interaction itself) as a threat to API longevity
  2. More importantly, and apparently not widely understood, Fielding doesn’t see the media type definition as being out-of-band. In fact it’s the media type definition that saves you from needing out-of-band information.

So what’s a media type and how do you create one? This is apparently widely misunderstood (including by me), and it’s surprisingly hard to find a simple answer.

In fact, there is a very simple answer. A media type is an information standard. You create one by writing it down. You can share it globally by registering it with IANA. The MIME types with which we are all familiar are simply pointers to this registry. Or, you can share it locally by just telling your mates where the standards document is. Here’s an incredibly simple example.


Again, the waters are muddied by people leaping immediately to the most difficult case, that of automatic discovery by generic automatons. If your “user agents” are developers, all you need in your media type documentation is human-readable text.

How to design a mashup

You can’t, of course. That’s the point of a mashup. You just “expose” some information and the genius of the crowd will then mash it together with other things in ways that you couldn’t possibly imagine, right? Hands-up everyone who thought that designing REST APIs is about exposing information (I have both hands up at this point). Unfortunately, this is utter nonsense, and even more unfortunately it doesn’t take much thinking to see that it’s nonsense. Who really believes that Google didn’t know people would be embedding maps with pins on them?

Fortunately, the talented guys at Jayway wrote a very nice article called Why hypermedia APIs? which reminded me that designing API’s is very closely related to designing applications (remember what the “A” and the “P” in API stand for?).


Designing applications starting with use cases is something I know how to do. Of course it’s blindingly obvious that API’s must also be designed with use cases in mind, but I had allowed myself to be almost terminally distracted by the mashup rhetoric along with with an abundance of bad examples.


Those were my three biggest pain points, which I’ll just restate here for easy access:

  1. What on earth is this HATEOAS stuff all about and what does it mean for my design?
  2. What’s a media type (really)
  3. How do I design something that will be used in “limitless and unimaginable ways”?

The resources I’ve pointed to in this post were invaluable in unconfusing me, so I hope they’ll help you too.

Leave a Reply

Your email address will not be published. Required fields are marked *