Blogger: Anne Thomas Manes
A recent thread on the OASIS XML discussion brings to light an important but often misunderstood REST principle. The subject line of the discussion thread was, "RESTful XML for updates", and the following question was posed: "I would like to update a representation without having to PUT the entire resource representation back to the server." i.e., the representation of the resource is an XML document, and the user wants to update one element within the XML document, and wants to transfer just the changed element rather than the entire document.
Scott (the person asking the question) provided an example: the resource is a "widget", and it has various attributes, including "status" and "color". The representation of this resource is an XML document with a root element called "widget" which has child elements called "status" and "color". So how do you update "status" without uploading the entire XML document?
Quite a few people responded, and the prevailing recommendation was to create separate URIs/resources for every "thing" that you want to access or update independently. One person recommended reading Joe Gregorio's treastise on How To Do RESTful Partial Updates. The discussion is informative, but I think Joe's suggestions impose too much burden on the user to understand the mechanics of his system. Which brings me back to the core topic of this post.
Look back at the original question, and you'll notice the source of the common misunderstanding: "I would like to update a representation without having to PUT the entire resource representation back to the server."
Scott should have said that he wants to update the resource, or more precisely, he wants to update the resource's state. The thing to remember is that a web resource is an abstract thing. It has a URI that names it, and through that URI and its uniform interface, a user can access and/or update its state. Users interact with the resource through representations of its state. But here's the kicker: The means by which you maintain the state of the resource should be invisible to users of the resource.
In this case, we're talking about a widget. As the provider of this widget resource, you need to maintain its state. But a user of the widget resource should not need to know whether the state is being maintained in an XML document, relational table, spreadsheet, or whatever. When the user performs a GET on the resource, you return a representation of the state of the resource--in this case, an XML document. But keep in mind that the XML document is not the actual resource. Even if you do use XML to maintain the server-side state, you shouldn't let the physical storage media constrain or restrict the means by which a user interacts with the resource.
If you want to enable users to update the status of the widget, then give them a URI that represent's the widget's status. When they update the status, your backend process must make the appropriate changes to the server-side state of the resource. From a developer's perspective, it's much easier to directly expose the physical state (e.g., the XML document). But as a resource provider, it's your responsibility to hide the limitations of your physical media from your users.