Erik Wilde on Services and APIs

Wednesday, May 22, 2013

XML PATCH

the PATCH Method for HTTP is a rather recent addition to HTTP, supporting partial resource modification. while it is similar to PUT in the sense that it is used to update an existing resource, it is similar to POST in the sense that it is neither safe nor idempotent (because applying the same patch two times can modify a resource two times). for a good overview of why PATCH may be good for your web services, mark nottingham's blog post is a great starting point.

one of the defining characteristics of PATCH is that PATCH requests are supposed to carry representations of how to patch a resource, meaning that such a request fully describes what the client is attempting to do. this means that you either have to add such a "patch model" to your media type (i.e., the design of your web service), or maybe you can reuse a patch model that has been defined elsewhere (and then you can simply use this media type for your PATCH interactions).

the recently published JSON Patch does exactly that: it defines a generic patch model for JSON, so that services that don't want to design their own patch model can simply use the application/json-patch+json media type for PATCH interactions (and the Accept-Patch header even allows servers to advertise the supported patch media types at runtime). JSON Patch defines its own patch model as part of the specification.

XML Patch is at a point now where we have one implementation, and we believe that other XML services (in particular generic XML services such as XML databases) might be interested to adopt the model, instead of having to define their own patch model for partially modifying interactions with XML resources. of course, service-specific patch models (defined in the context of specific XML-based media types) always can be better optimized to the data model of the service, but even if services do expose their own patch models, the Accept-Patch header allows services to advertise support for more than just one patch model.