Continuous partial debate

Sunday, 17 Feb 2008

Recently there has been a bit of a spat over a proposal for doing RESTful partial updates by Joe Gregorio. He bills it as a how-to, but considering that he closes with a list of open issues, I think that’s a bit of a misnomer. Rob Sayre criticises it as not RESTful, but I don’t see how it’s not: the URI is constructed via a server-published template and points to a GETtable synthesised resource, which is perfectly fine. I see the problem elsewhere, but let me get there by answering Joe’s questions and extrapolating from where that takes me.

  1. Do you have to include the xml:id attributes when you PUT back an update?

    Yes. Otherwise, if there are several editable elements with identical local-names in a row, how does the server tell which is which?

  2. Do the xml:id attributes appear when you do a GET on such a resource?

    Ditto.

  3. Obviously the representation of a partial update resource is not a valid Atom Entry. What should be the mime-type of that resource?

    The document element should not be atom:entry. This is not an Atom Entry Document; it’s merely a bag for a bunch of fragments with identifiers. Make it t:partial or something like that.

  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?

    There may be xml:id attributes present for purposes other than partial update. Overloading xml:id leaves the client with no idea about which elements are editable and which ones are merely fragment-addressable. Use t:edit-id instead of xml:id.

  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.

    No templates in atom:link. Applications expect URIs there (and specifically derefencable ones, for the most part). IANA Atom Link Relation Registry is fine; whether a client gets http://example.org/foo from an atom:link or constructs it via http://example.org/{id} in a t:link-template should be irrelevant.

  6. How do you handle descendents that aren’t children of the document element?

    There is no point in preserving the original document’s structure if you only want to ship fragments of it and all of the fragments are identified without reliance on the document’s structure. So you make no attempt to preserve the nesting of the original document, and just put all the identified fragments directly under the document element.

Once you take these steps (particularly #6 and #3 in combination), it becomes apparent that what you have here is a really no more than a home-grown patch format, just as Dare Obasanjo commented. The only uncommon feature of this proposal is the one Joe himself pointed out: it puts the server in control of what portions of the original document it is willing to allow partial updates on.

I don’t know if that’s a good idea; Dare thinks it’s not, and I’m inclined to agree.

But if you think it is, you could just as well go all the way: first, give this patch document format a MIME type. Then define a t:delete element to put under the t:partial document element, where it can appear any number of times, and whose content is the t:edit-id of an element to be deleted. Thus, the URI of the synthetic partial resource becomes unnecessary to interpret the patch document correctly. The bottom line is that you can stuff such a document into a PATCH request to the Atompub edit URI, obviating the URI construction gymnastics in entirety.

In essence, this is what Rob proposed, except for retaining the original proposal’s property of putting the server in control.