Why isn't the Flickr API RESTful?

Question

I'm about to start developing a REST API for a client's website and I've been doing some research. I came accross this useful SO question on the gold standard for APIs: http://stackoverflow.com/questions/297005

Prior to reading this post I'd thought about using the Flickr API as a point of reference. However this comment on the above question made me think twice:

The Flickr API is particularly hilarious, for example. It advertises itself as RESTful and yet is nothing of the sort! – NathanE

Firstly this suggests that I need to read more about REST till I completely understand it.

I'm particularly interested in what makes the Flickr API not RESTful and what affect these none RESTful elements have. Any insight anyone has would be very much appreciated.

Answer 1

• Incorrect use of HTTP verbs: Flicker uses the verb "replace" instead of HTTP PUT in http://api.flickr.com/services/replace/. Another example: http://api.flickr.com/services/rest/?method=flickr.test.echo&name=value "method" should be one of the HTTP methods (GET in this case).
• Flicker doesn't use HTTP status codes correctly.
• Authentication is not RESTful

Answer 2

Another important reason this API would be deemed unRESTful is because it doesn't make use of 'hypertext'. Hypertext is simply using links (and link relations) to move clients along in your applications, rather than requiring them to programatically 'construct' a URI.

This is not RESTful:

GET /collection
200 OK

<collection>
  <item>
    <id>1</id>
  </item>
</collection>

This is RESTful:

GET /collection
200 OK

<collection>
  <item href="/collection/1" />
</collection>

The benefit of the latter, RESTful, approach is that your server can move the item resource wherever it wants - e.g. move it to /item/1 - change the href value, and know that all clients will manage the change. The former approach is not capable of this because the server cannot guarantee that all clients will acknowledge the change; this is part of what is referred to as client/server coupling, and in large distributed systems where your API has lots of clients you want to keep this to a minimum - this is the primary objective of REST.

Roy Fielding refers to this part of REST as the 'hypertext constraint', and he wrote the following blog post about it:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven