Continuous partial debate
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.
Do you have to include the
xml:idattributes when you
PUTback 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?
xml:idattributes appear when you do a
GETon such a resource?
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:partialor something like that.
There are undoubtedly XML parsers that will choke on
xml:idattributes even though according to the XML specification the
xmlqname is reserved and should always be defined. Are these problems widespread enough to kill the use of
xml:idand warrant the creation of an id attribute in another namespace?
There may be
xml:idattributes present for purposes other than partial update. Overloading
xml:idleaves the client with no idea about which elements are editable and which ones are merely fragment-addressable. Use
t:link_templateelements 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:linkelement? Obviously the set of
t:link_templaterelations is a super-set of
atom:linkrelations. The same problem also exists for using URI Templates in HTML
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
atom:linkor constructs it via
t:link-templateshould be irrelevant.
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.