How To Do RESTful Partial Updates

Update 1: Wow, apparently using Atom as an example was a bad idea given the number of people with their knickers in a twist.

Update 2: Fixed the URI Template to accomodate Sam's nose.

Update 3: Good feedback from Tim Bray, Mark Nottingham, and Rob Sayre.

There are times when you have a large representation of a resource and only want to edit a small part of that resource. Wikipedia is a good example, where many entries in the encyclopedia are very long and you don't want to wade through all that wiki markup to correct a typo in one sub-section. To make it easier MediaWiki offers an edit link on each sub-section that allows you to edit just that sub-section. This same problem comes up in many other contexts, for example, editing a large Atom Entry via AtomPub, or working over a slow connections, ala a mobile device.

Just like the MediaWiki example, this can be done RESTfully and we'll construct just such a mechanism for AtomPub, and it should be obvious by the time we're done on how you can also do this for JSON.

So here's the goal: to be able to update and/or delete multiple sub-sections of a resource with a single request.

Starting from the MediaWiki example the easiest thing to do is define a URI for each sub-section we want to be updated. That gets us most of the way there, but only allows one sub-section to be updated at a time, and doesn't allow more than one sub-section to be updated in the same request.  So instead of having a single URI for each sub-section, we'll construct a URI that represents the set of sub-sections we want to update. And how shall we construct a URI? With URI Templates of course.

Here's a concrete example, an Atom Entry from an AtomPub Collection that lives at the URI http://example.org/edit/first-post.atom and has the following representation:

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
    <title>Atom-Powered Robots Run Amok</title>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <author><name>John Doe</name></author>
    <content>Some text.</content>
    <link rel="edit"
        href="http://example.org/edit/first-post.atom"/>
</entry>

Now if I wanted to update part of this entry, say the title, using the mechanisms in RFC 5023 then I would change the value of the title element and PUT the whole modified entry back to the the URI http://example.org/edit/first-post.atom. Now this document isn't large, but we'll use it to demonstrate the concepts. The first thing we want to do is add a URI Template that allows us to construct a URI to PUT changes back to:

<?xml version="1.0"?>
<entry         
        xmlns="http://www.w3.org/2005/Atom"
        xmlns:t="http://blah...">
<t:link_template ref="sub" 
        href="http://example.org/edit/first-post/{-listjoin|;|id}"/>
    <title>Atom-Powered Robots Run Amok</title>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <author><name>John Doe</name></author>
    <content>Some text.</content>
    <link rel="edit"
        href="http://example.org/edit/first-post.atom"/>
</entry>

Then we need to add id's to each of the pieces of the document we wish to be able to individually update. For this we'll use the W3C xml:id specification:

<?xml version="1.0"?>
<entry         
        xmlns="http://www.w3.org/2005/Atom"
        xmlns:t="http://blah...">   
    <t:link_template ref="sub" href="http://example.org/edit/first-post/{-listjoin|;|id}"/>
    <title xml:id="X1">Atom-Powered Robots Run Amok</title>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <author xml:id="X2"><name>John Doe</name></author>
    <content xml:id="X3">Some text.</content>
    <link rel="edit"
        href="http://example.org/edit/first-post.atom"/>
</entry>

So if I wanted to update both the content and the title I would construct the partial update URI using the id's of the elements I want to update:

http://example.org/edit/first-post/X1;X3

And then I would PUT an entry to the URI with only those child elements:

PUT /edit/first-post/X1;X3
Host: example.org

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
   <title xml:id="X1">False alarm on the Atom-Powered Robots things</title>
   <content xml:id="X3">Sorry about that.</content>
</entry>

Notes:

1. We keep the entry document element, ensuring that this it at least a well-formed XML document, but probably not a valid Atom Entry.
2. Absence of an element whose id is present in the partial update URI means that it is to be deleted.
3. You could also do a GET on the partial update URI to retrieve the current state of the sub-sections it identifies.
4. If no t:link_template/@rel="partial_upate" is found then the server doesn't support partial updates and you drop back to doing a simple PUT of the entire representation as defined in AtomPub.
5. This puts the server firmly in control of what sub-sections of a document it is willing to handle partial updates on.
6. The use of URI templates also puts the server firmly in control of the shape of the URI used for partial updates.
7. I didn't use a link element for the URI Template since URI Templates are not URIs. They become valid URIs after they're filled in, but the presence of the '{' and '}' characters means that they aren't valid URIs themselves.
8. This doesn't solve all the partial update scenarios, for example this doesn't help if you have a long sub-list that you want to append to.
9. You'll notice that I didn't give a good URI for the 't' namespace. I know better, if I did there'd be an implementation of this by the end of the day. One of the reasons I don't want to see that happen is that there are some open questions that need to be answered first:

Open Issues:

1. Do you have to include the xml:id attributes when you PUT back an update?
2. Do the xml:id attributes appear when you do a GET on such a resource?
3. Obviously the representation of a partial update resource is not a valid Atom Entry. What should be the mime-type of that resource?
4. There are undoubtedly XML parsers that will choke on xml:id attributes even though according to the XML specification the 'xml' qname is reserved and should always be defined. Are these problems widespread enough to kill the use of xml:id and warrant the creation of an id attribute in another namespace?
5. Can t:link_template elements use the same IANA Atom Link Relation Registry or do they need their own registry, or do we just hold our noses and put the URI Template in an atom:link element? Obviously the set of t;link_template relations is a super-set of atom:link relations. The same problem also exists for using URI Templates in HTML link elements.
6. How do you handle descendents that aren't children of the document element?

That last open question needs a little more explanation. If we had the id on name instead of author:

<?xml version="1.0"?>
<entry         
        xmlns="http://www.w3.org/2005/Atom"
        xmlns:t="http://blah...">   
    <t:link_template rel="sub" href="http://example.org/edit/first-post/{-listjoin|;|id}"/>
    <title xml:id="X1">Atom-Powered Robots Run Amok</title>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <author><name xml:id="X2">John Doe</name></author>
    <content xml:id="X3">Some text.</content>
    <link rel="edit"
        href="http://example.org/edit/first-post.atom"/>
</entry>

Then what does an update look like? Notice that name is a descendent of entry, but not a child. Do we include the author element on the update? That is, do we send:

PUT /edit/first-post/X2
Host: example.org

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
    <name xml:id="X2">John Doe</name>
</entry>

or do we send:

PUT /edit/first-post/X2
Host: example.org

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
    <author><name xml:id="X2">John Doe</name></author>
</entry>

So there you have it, outside of six open questions, a nice RESTful way to do partial updates.

<author>
    <name xml:id="X2">John Doe</name>
    <name>John Doe</name>
    <uri>http://example.org/</uri>
</author>

<x:update>
    <x:parts><!-- as above --></x:parts>
    <x:callback>http://example.com/someuri</x:callback>
    <x:some-other-non-payload-metadata>[...]</x:some-other-non-payload-metadata>
</x:update>

<entry xmlns="http://www.w3.org/2005/Atom"

<entry xmlns="http://www.w3.org/2005/Atom">