REST is in the eye of the beholder

The first time I came across the term REST must have been around 2005 or 2006 via Flickr, which was back then in many ways a pioneer in terms of how web applications should be built and designed.

REST, at the time, was a breath of fresh air and it seemed very sane in a world where SOAP and XML-RPC were dominant. I can look at a webservice straight from my browser? Wow. Returning simple XML documents instead of using XML as the transport made a lot of sense.

I’m not really sure if Flickr was the first to use the term REST for that type of service, but in my memory it played a fairly big part in popularizing it.

I used the wayback machine to find these early examples, but then quickly realized that the Flickr API has actually not changed!

But it’s not REST

It took me some time, but I slowly started realizing that this was actually not a REST service. Not before I deployed a similar API and stamped it “REST” though.

As it turns out, REST is more than “simple documents”. We learn we also need to use correct HTTP Verbs such as GET, PUT and DELETE where appropriate.

Over time the definition for me and many people around me evolves, which eventually brought me to a point where I found out what the original definition was all along.

REST stands for “Representational State Transfer” and was invented by Roy Fielding, one of the authors of HTTP/1.1 and described in his dissertation.

REST has a specific meaning and a ‘best practice way’ to implement it when using HTTP, and Flickr and pretty much anyone else joining the REST hype is getting it wrong, much to Fieldings annoyance (2008).

And he’s not alone. What follows is a storm of articles, conference talks, tweets and even some books describing what REST is and describing in what way many people got it wrong.

So what is REST?

Well, over time we’ve gotten better at describing what REST is. We now have the term HATEOAS, which rolls off the tongue amazingly. A service cannot call itself REST unless it’s also HATEOAS.

We also now have the Richardson Maturity Model, which is a bit like the seven stages of grief, but for REST. Basically, you cannot call your service REST unless you’re on Level 3 of the Maturity Model.

I’d highly recommend reading the fowler article, because it’s one of the best overviews. The maturity model maps out my personal learning curve as well.

But here’s the issue

I believe that “REST” is widely believed to be the “right” way to implement web services. The term is also almost universally used to describe services that actually are not hypermedia-driven a.k.a. not comformant with Level 3 of the Maturity Model.

Almost everyone gets it wrong.

But the thing that they got wrong is not necessarily the API they’ve built. It might be good (enough) and appropriate for what they are trying to accomplish. The thing they get wrong is that according to purists, they should not be calling their service REST, because it aint.

I think doing HATEAOS correctly is overkill for most people. Modelling it correctly is actually quite hard. It’s also prone to a lot of round trips.

A comment from Fielding:

REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency. Unfortunately, people are fairly good at short-term design, and usually awful at long-term design. Most don’t think they need to design past the current release. There are more than a few software methodologies that portray any long-term thinking as wrong-headed, ivory tower design (which it can be if it isn’t motivated by real requirements).

The reality is that a lot of us actually do see the value of achieving short-term goals, preferring ease-of-use over correctness. We’re not building an API for the library of congress. Having lots of people use an API is probably more important than that API being relevant for multiple decades.

What I’m really suggesting is that ‘correct REST’ is wrong for most people, but this leaves us with a major problem.

There’s a massive body of work that calls itself REST but is not quite REST. Any developer tasked with building a service might therefore come to the conclusion “REST” is a good thing.

Now, this developer might have questions about the design of their new REST service on Stack Overflow and find out that there’s a wild range of different answers based on the answerer’s definition of REST.

A common one might be: what is a good way to design my REST url structure? A ‘correct’ answer might be, the url structure doesn’t matter as all URLS must be discovered.

Correct? Yes! Helpful? No!

Developers might fight their way through it and still end up with enough resources and answers to develop their ‘not quite REST’-service.

Or alternatively, the developer might go all the way down the rabbit hole, and come to the conclusion:

  1. REST is popular choice for good API’s.
  2. Therefore REST is good.
  3. REST must be hypermedia-driven.
  4. Therefore good API’s must be hypermedia-driven.

I’ve seen many people fall for this logic trap, not realizing that it’s based on a false assumption. REST is not popular. Something that’s not quite REST is popular and everybody just calls it that.

We don’t have a good popular term to describe simple web API’s though, which makes it difficult to research. Most REST books and presentations you’ll find tend to be about ‘correct REST’ not ‘popular REST’, but most services are ‘popular REST’ not ‘correct REST’.

I think coming up with a new term and popularizing it is going to be very difficult though, so I propose that we let the programming lingo evolve the same way words’ definitions in languages do. “REST” is far and wide used to describe non-hypermedia API’s, so I think it’s safe to say that the term has evolved from it’s original meaning.

Sorry Roy. At least you still have HATEAOS.

Some further reading

Microsoft released a pretty great REST API Guidelines document that’s actually not hypermedia. If you’re looking for a body of work that does try to stick very close to the original definition of REST, take a look at Collection+JSON, which is highly correct and highly impractical.

Web mentions


  • J7mbo

    This is great!

    Not only are so many 'REST' APIs not actually RESTful, the same goes with many other things in tech.

    Take 'MVC' in web context, for example. Take some design patterns. All it takes is for a popular framework maintainer to spout nonsense mixed with marketing and you get a huge group of people believing that a Facade is actually something else, or in this case, non-RESTful is actually RESTful.

    Thanks for posting the above links, fowler etc, they're very useful :-)

    • Evert


      Well, I don't really care that much if meanings of terms get changed over time. I just think in this particular case it actually creates complications.

      • J7mbo

        It's not that the 'meanings of terms' have changed, it's that they still exist and are being inaccurately represented as fact - which is what seems to be happening here and what is annoying those purists (who sometimes help keep us on the straight and narrow).

        Regardless, it was a complement to your blog post and I tweeted it. Cheers!

  • philsturgeon

    Spot on. Whilst it's hard and usually not very helpful to "That's not actually RESTful" people, I try to separate what makes for a good "HTTP API" and a "Hypermedia API".

    A lot of people think they need REST when they don't need Hypermedia, struggle to implement it all, and call it REST anyway. It's a weird thing.

  • Alain Van Hout

    I've always found HATEOAS a weird match for the rest of REST (no pun intended, at this point):
    - it mixed data and meta-data, in contrast with the rest of REST, which aims to disentangle concerns
    - it insists that resource urls should be meaningless strings, while the rest of REST aims to add convenient semantics rather than reduce them
    - it tries to solve the issue of a changing API by (essentially) adding hard-coded strings to the definition of a resource, which in turn means that when the API changes, those hard-coded strings would become obsolete (excluding special measures be taken)

    So all in all, I see HATEOAS (REST 'proper', whatever that means) as being quite different than the rest of REST (as a result, for myself I tend to distinguish between 'RESTful' and 'restful').

    Excellent blog post btw!