Discrete Resource: a definition in support of XRX

Here at XML Today there is a strong and laudable push to promote XRX architecture. However, the very loosely defined REST architectural style leaves us a little short on best practice recommendations.

REST is usually presented as "Many nouns, few verbs," with the assumption that, because we know the verbs inside and out, we're going to save time and write simpler code. But really, we don't - we can't - know all of the HTTP verbs as thoroughly as we'd like.

Grappling with that particular problem yields one very basic architectural concept, the Discrete Resource. The characteristics of the Discrete Resource follow pretty naturally from consideration of the HTTP methods GET, PUT, and DELETE.

The Discrete Resource concept provides value in two ways: first, as a guiding term in best practice description for REST practitioners; and second, as an analytical tool for evaluating REST's applicability to a wide class of information management projects.

This concept has been a long time gestating, and it still feels a bit forced. I hope I can say it right. If anyone has critiques or comments, I'll be very glad to hear them.

This wasn't even the post I was planning to do, and it's been damned hard to write. However, it's gotten increasingly difficult to discuss REST and XRX in terms of an architect's professional responsibility without posting this first, so here goes.

One of these things is not like the other

If you spend some time with the definitions of the HTTP methods (the 4 main methods, I mean, the ones involved with REST) several things become obvious:

• GET, PUT, and DELETE are constrained in scope to the individual Resource named in their Request URI.
• GET, PUT, and DELETE work together seamlessly to manage that Resource's lifecycle.
  • If you perform a PUT, the content of the Request message body becomes the new representation of the Resource, such that
    • The response message-body of a subsequent GET will be the same as the message-body of that PUT request.
  • If you perform a DELETE, the Resource is not simply emptied of content; the Resource is deemed to no longer exist, such that
    • A subsequent GET request will receive a 404 Response.
• GET, PUT, and DELETE are well-constrained in terms of state effects:
  • GET is safe (thus, trivially, idempotent.)
  • PUT is idempotent.
  • DELETE is idempotent.
• ...and then there's POST.

Now, we all know that many Web Apps don't even remotely follow the specifications described above. I'm talking about the implications of the HTTP Specification, not about the rather messy state of compliance in the Web community at large. We don't expect a lot of strict adherence to anything in the Wild Web. POST, however, is different in that it is remarkably free of expectations even at the specification level. From the specification:

"The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line... The actual function performed by the POST method is determined by the server"

• A POST is not forbidden to affect any state, anywhere, as long as you can claim that that state is "subordinate" to the Resource. Databases? LDAP repositories? Site content? Sure, no problem as far as POST is concerned.
• POST operations are not required to be idempotent.
• POST is not expected to constrain its operations to the Resource identified by its URI. In fact, the URI of a POST request is more characteristically the URI of some engine (an engine that might do any number of things) that manipulates content not directly exposed as a Resource, rather than the URI of a single Resource.
• POST could emulate the action of a GET, a PUT, or a DELETE - it's not forbidden to do so. But, looking at the cozy resource-lifecycle relationship of GET, PUT, and DELETE noted above, POST has no defined part to play - no particular contribution at all, really, except to generalize the update of a Resource in a minor way: PUT is a replacement operation, an overwrite, the kind of update that discards all preexisting content for the thing being updated. If you want to do a changeset type of update, in which only the diffs, rather than the entire representation, are applied to the resource, POST could easily be used for that. However, that's not an inherent assigned role for POST in management of a Resource's lifecycle; it's just a nod to POST's flexibility. (And really: changeset updates are only an optimization, not a fundamentally different kind of action.)

Looking at all of this, it seems fairly obvious that avoiding the use of POST where it isn't needed would result in better implementations, and would drive cleaner architectures. However, the ordinary practice in Web App development is exactly the opposite. We treat POST as the default - an apparent case of "grab the most flexible tool you've got, and you won't have to think so hard."

Am I advocating discontinuing POST altogether? No, of course not. It's the only RESTful method for accomplishing a lot of real-world operations. What I'm advocating is that we avoid POST except in situations where we really need it.

If we were to avoid POST, what would the Web look like?

It would look like a lot of Discrete Resources, that's what it would look like.

OK, so, what's a Discrete Resource?

A Discrete Resource is a well-behaved Resource of a type implied - but not required - by the nature of GET, PUT, and DELETE. I'm calling it a Discrete Resource because, well, because it is. Here are its characteristics:

• The Discrete Resource's URI is its URL. In other words, the URL used to access the Resource is not the address of some separate engine that manipulates or represents Resources based on URI lookup. The URL is identical to the URI.
• The Discrete Resource is passive. It is an information representation. It is not an engine that conducts operations.
• The Discrete Resource has zero semantic depth. In other words, the Resource's surface Representation really is the semantic essence of the Resource, and not some derived "view" of a more fundamental or meaningful entity. (Semantically speaking. Of course Resources are often stored in forms such as databases, but from the semantic point of view, that's not significant.)
• The Discrete Resource is entirely under the control of REST operations. Emergency server maintenance aside, the Resource's representation is modified only by extrinsic REST operations.
• The Discrete Resource is logically isolated. GET, PUT, and DELETE operations against the Resource affect only that Resource and have no other effect on state.
• The Discrete Resource does not support POST, returning a 405 Method Not Allowed Response to any POST Request.

What are the advantages of Discrete Resource architectures?

These are the advantages I've thought of so far:

• You don't need to check a WSDL to find out how a Discrete Resource is going to behave. At most, you might need to check the Resource's documentation as to constraints on the permissible form of the Resource's Representation. In general, this means that a few highly general REST client front ends can be built, to serve all Discrete Resource access scenarios.
• Discrete Resources are by definition maximally transparent. There is no man behind the curtain; any system of Discrete Resources is highly regular and predictable. Problem domain analysis settles right where it belongs: on the structure, semantics, and properties of the various Resources' Representations.
• The transparency of Discrete Resources makes large-scale extrinsic search and discovery operations very tractable.
• Discrete Resources, by their nature, are not hidden in the Deep Web.
• Since Discrete Resources are logically isolated from one another, scalability is not an issue. You're free to deploy server resources in any desired fashion to support Discrete Resource publication.

There are probably quite a few others - can anybody suggest some? - but this list seems awfully compelling.

I assert at the beginning of this post that the utillity of Discrete Resources lies in the concept's ability to support 1) best practice enunciation, and 2) architectural analysis. I still believe that to be true, but I think I'll need to push those topics off into separate investigations.