Webs At Rest and In Motion

July 10, 2002

Kendall Grant Clark

Careful readers of XML.com have figured out by now that, editorially at least, we are interested in coming to terms with the REST (that is, "representational state transfer") approach to building applications, particularly Web applications. Leigh Dodds wrote a column recently ("REST Roundup") in which he discussed REST; and, before and during XML.com's coverage of the Google API debate, Paul Prescod, over the course of several articles -- "Google's Gaffe", "Second Generation Web Services", and "REST and the Real World" -- evangelized the REST architectural style of Web application construction.

It is safe to assume that all of this effort has gotten somewhere, that some developers have been convinced to consider REST more carefully, if not adopt it outright. That assumption is particularly safe precisely because REST is an "architectural style", which in practice means that it cuts across just about every other fundamental implementation decision.

The REST approach is open to Web application developers whether they prefer Unix or some other operating system, whether they think Apache is better (or worse) than its competition, whether they tend toward CGI, servlets, or distributed, loosely coupled tuplespaces, or whether they prefer Perl to Java, REXX to Visual Basic, Python to all four, and, if only management would see the light, Common Lisp to everything but Smalltalk. In short and in principle, anyone, no matter what other technical loyalties, constraints, or commitments they've undertaken, is free to employ REST principles when building Web apps. Which means, theoretically, at least, every Web developer could use REST to build her or his next Web app. As the marketeers say, REST has a great upside.

There is, then, a kind of conceptual ubiquity to REST which transcends most of the existing debate about how best to build Web apps. But it has another advantage, as well: REST is safe. Using REST principles is about as prudentially wise a choice as a Web developer can make. REST is safe because it is the architectural style of the Web itself, and, despite its flaws and warts, the Web just plain works and has been working, billions and billions of times every single hour, for years.

But there's another angle of view upon the safety of REST. Unlike other fashionable technologies, REST is not the result of an elaborate, a priori design, not the outcome of an ad hoc standardization process. It is, rather, the elaboration of the principles underlying the Web, the conceptualization of existing practice, arrived at after years of trial, deployment, testing, and real world shakedown.

REST's Best Practices

	Also in XML-Deviant The More Things Change Agile XML Composition Apple Watch Life After Ajax?

So far, so good. But if REST itself is a "best practice" for building network applications, that leaves open the question of REST's best practices. Given the choice between several existing architectural styles, it's prudent to choose the style which the Web instantiates and exemplifies, particularly when building Web applications. But that manifold practice of application design and construction will itself, in turn, exemplify vices and virtues, better and worse approaches. So what are the best practices of REST?

The rest-discuss mailing list has considered this question in some detail in past weeks. The conversation began with a message from Roger Costello, which suggested a few provisional candidates for REST best practices. Before turning to Costello's suggestions, however, I think it's worth noting briefly that many REST best practices, at least as the rest-discuss list formulates them, are what we might otherwise have called the aesthetics of URI design.

Which is just to say that some of the REST best practices merely state the properties of elegant and aesthetically virtuous (that is, contextually beautiful) URI design, which many Web developers have employed since long before REST was explicitly formulated. That simplicity, conceptual elegance, and beauty of URI design turn out to be positively related to what works best shouldn't really surprise anyone, and it's a useful and good thing to have that relation made explicit and widely known.

Costello's initial list included the following points.

• Every public resource should have a URI.
• A URI should expose no detail of its implementation; in Costello's terms, they should be "logical" rather than "physical".
• Since resources are objects rather than processes, URI parts should be named for nouns rather than verbs.
• Responses to HTTP GET should be free of side effects.
• The representation of a resource should contain links to other resources.
• Eliminate "query strings" as often as possible.

Based on the subsequent discussion of Costello's proposal, he added additional statements of best practice:

• Sort publicly exposed resources into those which are immutable by the client, the representations of which are accessible by HTTP's GET, and those which are mutable, the representations of which are accessible by HTTP's PUT, POST, or DELETE.
• Specify the representational schema of both mutable and immutable resources with a formal mechanism (DTD, W3C XML Schema, RelaxNG, Schematron, and so on); that is, publicize the format of what your application expects, accepts, and returns.
• Use WSDL or some other means to specify the ways in which your application may be invoked.

The subsequent discussion of Costello's proposals focused on two points: whether query strings should really be minimized, and whether URI parts should be named by nouns rather than verbs. The latter question may seem trivial, but it rests on different conceptions of what REST means.

If you see the basic constituents of HTTP (GET, PUT, POST, DELETE) as actions which transfer a representation of the state of a resource named by a URI, then you'll tend toward the view that URI parts should be named by nouns rather than verbs. On this view, URIs are things which are acted upon by HTTP methods and the result of those actions is to transfer representations of some resource from the origin server to the client which initiated the request. In which case, some URIs which have parts named by verbs make little sense.

There is a lot left to be said about REST, and the rest-discuss list is likely to be one place where some of it is said. For example, one issue that's been mostly under discussed so far is the relation of WebDAV -- and its HTTP extensions -- and the REST architectural style. Do any of WebDAV's new methods violate the principles of REST? And, if not, how do those methods affect the design and implementation of Web applications in new and interesting ways? How can REST-friendly Web developers use WebDAV's resource versioning and locking, management of resource collections, and resource metadata management? If you're interested in extending your grasp of the REST architectural style, subscribing to rest-discuss is a good first step.