« PATCH is still better than POST
XML Patch Format »

PATCHes and Cream

It took several months, but we’re finally getting some really good discussions going about PATCH….

For the most part, throughout all of the comments I’ve seem, a common thread seems to be emerging that the current definition of PATCH as spelled out by the current draft (which I’ve taken over from Lisa, btw) is adequate. At issue, however, are the patch formats — that is, how to describe the list of changes that need to be made to any given resource.

Every resource is different, and different patch formats will be required. For JSON documents, for instance, you could use the format described by Rob:

PATCH /a/json/object HTTP/1.1
Host: example.org
Content-Type: x-application/json-sync

[
 {"action":"edit", "path":["x"], "value":43},
 {"action":"remove", "path":["b", "d", "f"]},
 {"action":"create", "path":["b", "new2"], "value":22},
 {"action":"remove", "path":["h"]},
 {"action":"create", "path":["i", "3"], "value":99},
 {"action":"edit", "path":["n"], "value":{}},
 {"action":"create", "path":["n", "new3"], "value":77},
 {"action":"create", "path":["new"], "value":11}
]

However, I’m not sure why we could just post the javascript directly… 

PATCH /a/json/object HTTP/1.1
Host: example.org
Content-Type: application/javascript

var localCopy = clone(serverCopy);
localCopy.x = 43;
localCopy.new = 11;
localCopy.b.new2 = 22;
delete localCopy.b.d.f;
delete localCopy.h;
localCopy.i.push(99);
localCopy.n = {"new3": 77}

For XML documents, we could use XQuery Updates or any number of the various other XML-diff formats that have been proposed. It still annoys the hell out of me that no single xml patch format has been developed…

This entry was posted on Sunday, February 17th, 2008 at 9:41 amand is filed under Technology, standards, patch.
You can follow any responses to this entry through the Atom Comments feed. Responses are currently closed, but you can trackback from your own site.

10 Responses to “PATCHes and Cream”

  1. Robert Sayre Says:
    February 17th, 2008 at 11:11 am

    well, there are lots of reasons not send code around, but the technique in sync.js doesn’t require that a log be kept.

    var foo = {x:1,y:2};
    var bar = clone(foo);

    bar.x = 0;
    bar.y = 3;
    delete bar.x;
    bar.x = 1;

    print(detectUpdates(foo, bar));

    [
    {”action”:”edit”, “path”:[”y”], “value”:3}
    ]

  2. James Says:
    February 17th, 2008 at 11:28 am

    It’s definitely a nice approach. I wonder if it could be adopted to XML also?

  3. Joe Gregorio Says:
    February 17th, 2008 at 11:48 am

    “It still annoys the hell out of me that no single xml patch format has been developed…”

    Because XML is an order of magnitude messier than JSON. Do you want to be able to PATCH DocTypes? How about processing instructions? How about replacing a character entity with it’s value? I know you can come up with answer for each one of these questions. It’s the fact that you have to ask them to begin with that’s the problem. JSON is refreshingly lacking these “features”.

  4. James Says:
    February 17th, 2008 at 12:07 pm

    I’m only interested in addressing the issues people actually have. E.g., I’ve never heard anyone ask for the ability to patch doctypes. The solution becomes a lot easier to come up with if we reduce the number of questions that have to be asked.

  5. Mark Nottingham Says:
    February 17th, 2008 at 3:37 pm

    [posted to Mark Baker’s blog before I saw this, but equally applicable here]

    The interesting question, to me, is whether client-side toolkits will evolve to the point where they’re smart enough to realise that they should PATCH when the user says to PUT — and whether that’ll be considered a feature or a bug.

  6. James Says:
    February 17th, 2008 at 6:11 pm

    Given a usable patch format, I could likely add support for that to Abdera pretty quickly.

  7. Noah Slater Says:
    February 18th, 2008 at 4:50 am

    On a number of applications I have developed I have needed to alter the DOCTYPE, PIs and perform some sort of c14n while passing documents around. I should imagine that for those working with XML these PATCH methods are very much a requirement.

  8. James Says:
    February 18th, 2008 at 8:11 am

    Noah, interesting. If I may ask, what kind of alterations to the doctype needed to be made?

  9. Keith Fahlgren Says:
    February 18th, 2008 at 9:25 am

    IMHO: If you want to edit the DOCTYPE, you get to PUT a new document. PATCH is clearly an optimization for speed/efficiency, not some bucket into which everyone can throw their pet features….

  10. Noah Slater Says:
    February 19th, 2008 at 12:14 am

    James, the document processing application was responsible for correcting the DOCTYPE and removing PIs as part of a home-brew c14n process. It was essential to standardise on a common set of shared entities, protect from things like the billion laughs attack and remove any potentially dangerous processing instructions before handing off to 3rd party applications.

    If I were using a RESTful storage medium (like CouchDB) I might have wanted to perform these operations as PATCHes, especially if the documents were large.

    Having said that, the system I was working handled multiple variants so that the http://example.org/db/document-a/ resource might have HTML/XML/PDF representations available via content negotiation. I’ve yet to see a proposal of PATCH that would be able to reliably specify a specific representation to update.

    The only mention in the draft-dusseault-http-patch-11 draft doesn’t offer a solution:

    “The client attempted to modify a resource that has multiple representations but the server was unable to choose which representation to modify.”

    With out ability this the whole discussion is mute, at least from my POV.