Erik Wilde on Services and APIs

Saturday, March 17, 2012

PATCHing AtomPub

the Atom Publishing Protocol (AtomPub) predates HTTP PATCH, and therefore there is no way how it could explicitly allow updates to be made via HTTP PATCH instead of PUT. but instead of allowing any update method, both the edit and the edit-media link relation type hardcode the fact that updates are made by using PUT. this means that conforming implementations have to support PUT (and maybe they can support PATCH; supporting other methods is neither explicitly allowed nor disallowed by the spec).

one of the advantages of PATCH is that updates can use any kind of diff format that is deemed appropriate for the application, and thus (in case or larger resources, for examples) it may be desirable to use the general patterns established by AtomPub, but to allow updates by PATCH, maybe in addition to PUT, or as the only allowed method for updates. but what would it take to PATCH-enable AtomPub? there are (at least) three possible answers, and i am curious to see whether there is some community consensus for the best one.

do nothing: maybe the interpretation that updates must be made by using PUT is overly narrow and the fact that neither edit nor edit-media mention the required method allows us to stretch the interpretation of AtomPub a little and assume it is ok to also or only allow PATCH? (i guess my quotation marks make it clear that i don't think this would be the proper way to do it.)

add new links: it would be possible to define patch and patch-media link relations, which would be explicitly defined to use be used with PATCH. it would be a bit unfortunate to have two links instead of just having one edit link that could be used with OPTIONS to learn about the available methods, but one could argue that the fault lies with AtomPub's hardcoded PUT, and thus this has to be done to not mess with AtomPub semantics.

create an AtomPub profile: another approach would be to allow OPTIONS on edit and edit-media and thus allow clients to explore the available methods. this could be signaled by a profile link in the feed or entry, and clients supporting that profile would know that they could use OPTIONS. clients not knowing this profile would simply have to deal with the fact that some edit/edit-media links might return 405 (Method Not Allowed) errors, but REST clients should be able to deal with this kind of failure scenario anyway.

any opinions or comments about these three options are highly welcome, and in particular any pointers to implementations that use AtomPub and already support PATCH. if there is some community consensus, it would be interesting to see whether it would be strong enough to move forward with option 2 or 3 and turn it into a formal spec (and if everybody is fine with option 1, then no action is required anyway).

@benjamin, thanks for the pointer. regardless of when it appeared, that doesn't change the fact that strictly speaking the current AtomPub spec does not allow PATCH, right? the main reason for writing this post was to figure out how we can PATCH-enable AtomPub, and i guess there are at least the variants that i have proposed, and maybe more.

thanks @prathe for your comment. 2 and 3 would need some form of consensus, in the form of registered/well-known link relations or a well-known profile (and the 'profile' link relation type itself is not yet standardized). cooperating communities could start using approaches 2 and 3 right away, but for it to become an expectation than could be supported in general-purpose atompub clients, there would need to be consensus around the link relations or the profile URI.

it might be most elegant to just rely on 'edit' and OPTIONS, and 1 suggests that it might be safe to just use this right now, but i think for clients to be aware of this (use OPTIONS on the 'edit' link to find out about PUT and/or PATCH support), it should be added to atompub itself. then you would end up with 'old' atompub (just PUT) and 'new' atompub' (use OPTIONS), but old clients could still happily live with new services, only that they would never discover the ability to use PATCH instead of PUT.