I've slowly been appreciating the wisdom in using REpresentational State Transfer (REST) as the architectural style for building services on the Web. My most recent influences have been Nelson Minar's ETech presentation entitled Building a New Web Service at Google and a discussion on the XML-DEV mailing list last week.

The REST architectural style was first formally defined in Chapter 5 of Roy Fielding's Ph.D dissertation. It's principles are succintly distilled in the Wikipedia entry for REST which currently states

REST's proponents (sometimes referred to as RESTafarians) argue that the web has enjoyed the scalability and growth that it has as a result of a few key design principles:

  • A fundamentally stateless client/server protocol: each HTTP request/response pair is complete in itself, and participants are not required to take additional steps to track states (though in practice, many HTTP servers use cookies and other devices to maintain a session state).
  • A limited number of well-defined protocol operations: HTTP allows very few verbs, the most important of which (for REST) are GET, POST, PUT, and DELETE. These correspond fairly closely with the basic CRUD functions required for data persistence.
  • A universal means of resource-identification and -resolution: in a RESTful system, every piece of information is uniquely addressable in a single namespace through the use of a URI .
  • The use of hypermedia both for application information and application state-transitions: the resources in a REST system are typically HTML or XML files that contain both information and links to other resources; as a result, it is often possible to navigate from one REST resource to many others, simply by following links, without requiring the use of registries or other additional infrastructure.

These principles can be further distilled to the simple phrase, "Just use HTTP". However the problem with this is that lots of people actually don't use HTTP correctly. This ranges from the fact that many HTTP-based systems don't support the DELETE and PUT to the fact that many services based on HTTP ignore the specification that HTTP GET requests should be idempotent and safe. About the latter issue, the HTTP specification states

9.1 Safe and Idempotent Methods
9.1.1 Safe Methods

Implementors should be aware that the software represents the user in their interactions over the Internet, and should be careful to allow the user to be aware of any actions they might take which may have an unexpected significance to themselves or others.

In particular, the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval. These methods ought to be considered "safe". This allows user agents to represent other methods, such as POST, PUT and DELETE, in a special way, so that the user is made aware of the fact that a possibly unsafe action is being requested.

9.1.2 Idempotent Methods

Methods can also have the property of "idempotence" in that (aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request. The methods GET, HEAD, PUT and DELETE share this property. Also, the methods OPTIONS and TRACE SHOULD NOT have side effects, and so are inherently idempotent.

There are a number of reasons for HTTP GET requests to be both idempotent and safe. Being idempotent means that various caching systems between the user and the web server from the browser cache to caching proxies can cache the request without worry that the web server was supposed to service that request. And as Sam Ruby pointed out in his post AJAX Considered Harmful being safe means unsuspecting grandmothers and bots everywhere cannot be tricked into modifying online databases simply by following a link.

However a number of web services that have been held up as examples of RESTful APIs actually violate these principles. These include the Bloglines sync API, the Flickr API and the del.icio.us API.

  1. An example of where the Bloglines sync API uses HTTP GET requests in a way that is not idempotent or safe is the getitems method which has a parameter to "mark unread items as read".

  2. An example of where the Flickr API uses HTTP GET requests in a way that is not idempotent or safe is the flickr.photosets.delete method which deletes a photo set.

  3. An example of where the del.icio.us API uses HTTP GET requests in a way that is not idempotent or safe is the http://del.icio.us/api/posts/delete function which 
    deletes a post from delicious.

This isn't to say all popular web services held up as RESTful APIs actually aren't. The Atom publishing  protocol is an example of a RESTful API that actually honors the principles behind  HTTP. However there are a number of plain old XML (POX) web services which people have begun to conflate with RESTful services which led to some confusion on my part when I started trying to figure things out in this space.

A good place to start when deciding to design a RESTful system is Joe Gregorio's article How To Create a REST Protocol.


Categories: XML Web Services
Tracked by:
"standards" (Bruce Landon's Weblog for Students) [Trackback]
"[OIN-179] Creating safe REST access" (JIRA: OpenInteract2) [Trackback]
"Indigo Embracing POX and REST web services?" (Dare Obasanjo aka Carnage4Life) [Trackback]
"Blog Neighborhoods" (basement.org) [Trackback]
"Hi-REST/Lo-REST Pushback" (Dare Obasanjo aka Carnage4Life) [Trackback]
http://fiatdev.com/wp/2006/06/27/some-rest-resources/ [Pingback]
http://www.chipsquips.com/?p=398 [Pingback]
http://jawf5j3.net/storage/sitemap1.html [Pingback]
http://pcbaqlu.net/01/sitemap1.html [Pingback]
http://otjjblj.net/05/index.html [Pingback]
http://lbxaveg.net/02/index.html [Pingback]
http://kf7ujzd.net/southwest/sitemap1.html [Pingback]
http://lordless.250Free.com [Pingback]
http://lf0s3on.net/storage/sitemap1.html [Pingback]
http://biggest-hosting10.com/~rocata/linux/index.html [Pingback]
http://host239.hostmonster.com/~blogford/sitemap1.html [Pingback]
http://gator413.hostgator.com/~digital/handbags/sitemap1.html [Pingback]
http://ezjhep4.net/sitemap1.html [Pingback]
http://hgxi0w2.net/sitemap1.html [Pingback]
http://rmarvwy.net/furniture/index.html [Pingback]
http://box432.bluehost.com/~zbloginf/sitemap1.html [Pingback]
http://gator442.hostgator.com/~hockteam/tattoo/sitemap1.html [Pingback]

Sunday, 03 April 2005 22:43:09 (GMT Daylight Time, UTC+01:00)
Good post.

A subtle point worth mentioning... HTTP DELETE is not safe, but it is idempotent.

Monday, 04 April 2005 01:33:30 (GMT Daylight Time, UTC+01:00)
For what very little this may be worth, I went through a similar phase of suddenly appreciating REST about 3 years ago. I got pretty enthusiastic about its potential as compared with the WS stuff, but ended up rather disillusioned. I think you (and David Megginson, in his latest post) have touched on some of the reasons: URIs + GET is really the secret sauce for much of the Web's success, and HTTP+POX works awfully well for read-only applications where some code has to process data that traditionally a human would read. It's easy to see that GETting some POX makes a lot more sense for something like the Amazon browsing API or the Google query API than SOAP+POST, even with all the tools that support that stuff. I endorse what would appear to be your efforts to apply this at MSN.

BUT what happens when things get more complicated? As you point out, there's not much evidence that site builders are using REST principles even though they are definitely having lots of success at the intersection of HTTP and XML.

The question I continue to ask is: Since most of the successful services said to be examples of how great REST is are not actually RESTful, what does that say about REST as a prescription for how to build a proper website or service? Does it imply that one SHOULD build services that conform to the principles in the Wikipedia article, essemtially taking on faith that they make sense irrespective of the evidence? Or does it imply that there is some other principle -- KISS, the network effect, some intrinsic goodness of HTTP+XML -- at work here that we should try to identify before making prescriptions?

FWIW, a couple of years ago I personally concluded that it's definitely the KISS principle at work here, powered by the fact that HTTP and XML are so universal. REST theory intersects this, but the degree of conformance to the other bits of REST theory does not seem to predict which sites will work. The obvious example is cookies, but all the app server / J2EE infrastructure that maintains server-side state without exposing it to the client app is another counter-example.

So, IMHO, HTTP+POX has got a lot of mojo flowing that should by all means be harnessed. But it will be interesting to see if others come away as disillusioned by the, uhh, rest of REST as I have been.
Monday, 04 April 2005 01:59:57 (GMT Daylight Time, UTC+01:00)
Broken link: "Chapter 5 of Roy Fielding's Ph.D dissertation". Should be: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Btw, I'm reading the entire dissertation. Great stuff.
Monday, 04 April 2005 02:40:09 (GMT Daylight Time, UTC+01:00)
Thanks for pointing that out. The link is fixed.

REST as described in Roy's dissertation is an attempt to describe the way the Web works. However theory and practice often differ. Still, I think that basing building services on the Web on the Web's arhitecture instead of trying to build a separate infrastructure on top of it makes a lot of sense. The success of the Bloglines, Flickr and del.icio.us APIs show that one can go beyond "read-only applications where some code has to process data that traditionally a human would read" with services that are built following the techniques that powers the rest of the Web.

Although the Bloglines, Flickr and del.icio.us APIs aren't RESTful, it wouldn't take much to make them RESTful. Secondly the primary worries around HTTP GETs being idempotent and safe are somewhat reduced when one has to go through a layer of authentication to complete the request.

From where I sit using RESTful techniques (including POX/HTTP) build on the experiences and nature of the Web. In retrospect, it seems obvious that this should be the way to build services on the Web.
Monday, 04 April 2005 14:05:07 (GMT Daylight Time, UTC+01:00)
"building services on the Web on the Web's arhitecture instead of trying to build a separate infrastructure on top of it makes a lot of sense." Absolutely. I simply question whether Fielding's description is close enough to reality to be taken seriously as a *prescription." Is there evidence to indicate that sites that follow the prescription actually work better? All I know is that an awful lot of successful sites don't seem to.

BTW, "safe" and "idempotent" are terms defined and discussed in the HTTP spec itself. I agree with your suggestions but, as I understand it, you are suggesting that Bloglines, Flickr, etc. conform better to HTTP, not that they be more RESTful.

So all I'm saying here is let's be careful to understand the distinction between "the web architecture" as it exists in practice and as REST describes it in theory, and to understand the distinction between HTTP the spec and REST the theory for how to build systems on top of the spec. I came away from my flirtation with RESTifarianism with renewed respect for HTTP, but with greater skepticism about REST. It will be very interesting to see if the new generation of REST converts has a similar disillusionment, or if they manage to ratchet the level of practice up to a point where some of the more challenging ideas (e.g. the "engine of application state" when there is no human mind to drive the state machine by clicking on interesting links) turn out to be fruitful.
Monday, 04 April 2005 20:23:24 (GMT Daylight Time, UTC+01:00)
"I agree with your suggestions but, as I understand it, you are suggesting that Bloglines, Flickr, etc. conform better to HTTP, not that they be more RESTful."

Dare is suggesting they do both. Those APIs are inventing micro-protocols in the query string, and thus fail to present a uniform interface (Is this *really* a GET?).

Tuesday, 05 April 2005 00:11:01 (GMT Daylight Time, UTC+01:00)
"Secondly the primary worries around HTTP GETs being idempotent and safe are somewhat reduced when one has to go through a layer of authentication to complete the request."

Small point: "safe" in this context isn't related to security (authentication), it's about unintended side-effects.

A web spider, such as a link checker, running against a password protected site is just as much at risk of bad-GET side-effects as sites in the wild.

I ran into this problem myself when I wrote my comment spam deleter, I used a link instead of a button+POST to delete a comment. After 20 or so deletes and the browser isn't caching pages anymore, hitting "Back" causes the page to be reloaded. Oops. Using POST, the browser would have prompted before reposting.
Tuesday, 05 April 2005 00:44:19 (GMT Daylight Time, UTC+01:00)
I understand what safe means in context of HTTP. My point was that it was less likely for bots or an unsuspecting grandmother clicking a link to trigger an unexpected event if they have to provide some sort of authentication before the request is sent.
Tuesday, 05 April 2005 18:28:02 (GMT Daylight Time, UTC+01:00)
You are pointing out that REST in theory is different from HTTP in practice. This doesn't mean that REST is not elegant, just that most sucecssful web sites cannot be explained by faithful application of REST. In practice, nobody uses PUT or DELETE, and people chose between GET and POST based on other critera than suggested in the Fielding paper. Hiding side-effect-generating operations from a search engine is only one small consideration.
Comments are closed.