This is a single archived entry from Stefan Tilkov’s blog. For more up-to-date content, check out my author page at INNOQ, which has more information about me and also contains a list of published talks, podcasts, and articles. Or you can check out the full archive.

RESTful

Stefan Tilkov,

One of the claims often made against REST is that there's a lot of disagreement around it – that nobody can define whether something is RESTful or not.

I was reminded of this in a recent discussion, and I claim it's bullshit. The REST community actually very easily agrees on whether or not something is RESTful or not when it's put up for judgement. And the nice thing is that you can easily get very close to answering this yourself by looking at a Web API that claims to be "RESTful", and see if it really is using a few simple questions:

  • Do the URIs actually identify resources, or do they encode operations?
  • Are the HTTP verbs – GET, PUT, POST, DELETE – used according to their defined meaning? Or is e.g. a GET used for operations that have side effects a client would not want when following a link?
  • Is hypermedia used, i.e. are there links in the representations that a client can follow?
  • Are MIME types used to differentiate data types (in Accept and Content-type) headers?
  • Are caching and conditional GET supported, i.e. are there appropriate cache control headers and ETags?

I claim that if you answer "yes" less than four times, your API is not RESTful. If you answer yes five times, you may still not have everything 100% correct – but you've built something that's very good compared to the average, and can have meaningful discussions about how to improve it even more.

(Check out these articles for more background: intro, rest anti-patterns.)

On December 12, 2008 5:06 PM, Colin Jack said:

I like this list but wanted to refer you to two other posts:

1) Alan Dean on a RESTful basket (http://alandean.blogspot.com/2008/11/on-restful-basket-state.html). 2) Roy Fielding on hypertext-driven constraint (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven) which seems to be enforce more than you do here.

I only mention them as from what I’ve seen different people do mean different things when they describe something as RESTful, maybe the differences are subtle though?

Also when you use the term RESTful do you always mean REST + HTTP, just interested on this point.

I also want to report two issues with the blog software you are using:

1) Failing to type in the captcha code correctly takes you to an error page but gives you absolutely no way to get the text you typed in back. I’ve now typed this entire post in twice and it made more sense the first time :) 2) I now have two Movable Types accounts but neither let me login despite me asking it to generate new passwords, it won’t let me login using my OpenID either.

On December 12, 2008 5:55 PM, Stefan Tilkov said:

regarding 1) I’m with Subbu (if you look at his comments to Alan’s post) – I prefer to model a shopping cart as a resource in its own right. But this is IMO not a critical issue, more of a design decision.

regarding 2) (Roy’s post): Who am I to disagree with Roy, as anything he says about REST is almost right by defintiion. But while I believe I get his points and agree with them, I also agree with Sam Ruby that there are degrees of compliance here (see http://intertwingly.net/blog/2008/10/21/Progressive-Disclosure). Thanks for pointing me to the post again, though, it’s got great comments and I’m learning a lot reading through them right now.

As to “REST” and “RESTful”, I almost exclusively use them to describe REST as supported by HTTP, or HTTP and other Web standards used in a RESTful way, unless the distinction to REST the architectural style is important.

And finally: sorry about your commenting trouble, I’ll try to fix it later.

On December 13, 2008 1:39 PM, Colin Jack said:

Ta for taking the time to reply and I like the idea of degrees of compliance, I wonder how far you can go without losing the architectural advantages that REST provides though.

On December 13, 2008 1:55 PM, Colin Jack said:

One more comment, you don’t mention standard media/content types explicitly but some people seem to see that as key. As an example Duncan Cragg (http://duncan-cragg.org/blog/post/content-types-and-uris-rest-dialogues/) has explained his views on it in some detail.

Actually in general the I think the REST oriented design of content-types and schemas is inadequately explained. Mind you I find many things are inadequately explained which is why I’m glad some of you are now writing books! :)