< Game Roundup: DS Homebrew Edition
Next >

Leonard's Web Service Maturity Heuristic: In my QCon talk (video coming eventually) I told three stories, This American Life-style. This weblog entry summarizes the third story.

By now it's a cliche to observe that allegedly "RESTful" web services like Amazon's SimpleDB and the Flickr web service and the del.icio.us web service aren't really RESTful. But there's something about them that makes their creators distinguish them from SOAP-based web services (by calling them "RESTful"), and there's something about those services that users love despite the possibility of, eg. deleting data by accident.

Rather than say one service is more or less "RESTful" than another, attempting to quantify an easy-to-misuse term that wasn't even intended to be used in relation to web services, I've found it useful to judge web services based on how many of the web technologies they adopt. Think of the World Wide Web as having a technology stack that looks like this:

Hypermedia (ie. HTML)

In every case I know about, people build web services from the bottom of the stack. They pick some point on the stack and take the technologies below that point seriously. The technologies above that point are not considered important. They're ignored, or used to the minimum extent you can get away with and still technically be a "web service".

XML-RPC and SOAP services are at level zero. They don't take any of the web technologies seriously. They use one URI, one HTTP method, none of the interesting features of HTTP, and they have no notion of hypermedia.


The web services I mentioned at the beginning of this entry are at level one. They take URIs seriously and assign a URI to every aspect of the system. But they only use one HTTP method (GET) and don't use any of the interesting features of HTTP. Nonetheless, people love these web services, because people love URIs.


Amazon S3 is at level two. It has problems (or so I've heard) with its use of HTTP, but it takes HTTP seriously. It uses URIs to designate objects in the system that can be operated on with different HTTP methods. It takes advantage of HTTP's features like conditional requests. But there's no hypermedia. All the information about how to manipulate the resources, and how to detect the connections between them, is in English documentation that you have to read when writing your custom S3 client.


Most of my current thinking is hypermedia-related. Useful here is the formal definition of hypermedia, from 4.1.3 of the Fielding dissertation: "Hypermedia is defined by the presence of application control information embedded within, or as a layer above, the presentation of information."

Services like the Web, AtomPub, the Netflix web service, and the Launchpad web service are at level three. They serve documents with embedded "application control information": links and forms that give a more or less generic client hints about how to manipulate this particular web service.

There are degrees of quality within these levels. For instance, big parts of the Web use URIs to name operations, rather than the objects those operations can act on. I think that's bad design, but that's a problem on level one. It doesn't negate the value of HTTP or hypermedia. Similarly, when we have the well-worn argument about which HTTP methods a web service should expose, we're having an argument on level two, not an argument about who's more RESTful. In fact, almost all the currently raging arguments are level one or level two arguments, which is unfortunate as there are some really great flamewars to be had on level three.

I don't intend to defend this classification technique in detail. It's a set of heuristics. In theory you could take URI and HTML seriously but not HTTP; or HTML and HTTP but not URI. But the heuristics are useful in that they 1) encapsulate a fact about how people tend to design web services, 2) make it easy to classify an argument or problem, 3) let you make a snap judgement of how much Web knowledge went into a web service, 4) make it easy to think about RESTfulness (an abstract meta-architectural concept) in terms of specific technologies you should know about already, technologies that are probably the reason you care about REST in the first place.

Filed under: ,

[Main] [Edit]

Unless otherwise noted, all content licensed by Leonard Richardson
under a Creative Commons License.