Sorry, but the Flickr API isn't REST

Feb 21, 2008 · 3 minute read

After SemanticCamp me and Rey popped in to see Paul and everyone at Osmosoft towers. A good few interesting conversations ensued, including one about the difference between mashups and integration. All good fun basically. Simon also had an interesting take on the topic as well.

What has all this to do with the topic of this post? Well, Simon says:

When compared to small RESTful APIs like flickr and twitter…

Now I’m not really picking on Simon here, more that I’ve been meaning to write something on this topic for a while and this proved a good catalyst for a little rant.

The flickr API is pretty darn cool. But it’s not RESTful in pretty much any way you want to shake a stick at it. It’s a well designed RPC (remote procedure call) API. Now even flickr get this wrong. They even have a page which confuses the issue and makes REST out to be a response format based on XML. Bad flickr.

flickr states that:

The REST Endpoint URL is http://api.flickr.com/services/rest/

This turns out to be completely against the whole RESTful principles. Lets try and explain. You can define most of what you want to do with an API with the use of nouns, verbs and content types. REST is based around limiting the set of verbs to those available in HTTP; for instance GET, POST, PUT and DELETE. For any given application or API you’ll also specify a set of content types (representations); for instance HTML, JSON or XML. All you get to play around with are the nouns, in the case of the web these are our URLs.

In a typical RPC style API you have one URL (like flickr does) which acts as the end point to which all calls are made. You then probably define a few functions which you can call. Lets look at a simple book example.

<code>getBook()
deleteBook()
createBook()
editBook()</code>

The RESTful way of designing this might look a little bit more like this:

<code>GET     /books/{book-id}
DELETE  /books/{book-id}
POST    /books
PUT     /books/{book-id}</code>

We mentioned content types or representations earlier. Lets say instead of the default response format we might want to get a JSON representation of a given book we might do something like the following.

<code>GET /books/{book-id}.json</code>

The advantages of using URLs as the API nouns in this way include more than just sane URLs for the site or application in question. The web is based around many of these architectural principles and that seemed to scale pretty well. The idea is that fell envisaged RESTful applications have an advantage here too. For me one of the real benefits of RESTful APIs are in the simplicity they bring to documentation. I already know the available verbs, all I need to know are the set of resource URLs and I can probably use CURL to work out the REST (sorry, bad pun).

This misunderstanding is pretty common. Even WikiPedia appreciates their is a problem:

The difference between the uses of the term “REST” causes some confusion in technical discussions.

This isn’t just pedantry on my part, well not quite. I’d recommend anyone involved in designing and architecting web sites read RESTful Web Services as well as Roy Fielding’s Architectural Styles and the Design of Network-based Software Architectures. But if you just want to get the general principles and don’t fancy wading through technical documents then you have to read How I Explained REST to My Wife hilariously written by Ryan Tomayko.

And remember, just because an API makes use of HTTP doesn’t make it RESTful. I’m looking at you twitter.