mark nottingham

Why you are not using XQuery Update (https://www.w3.org/TR/xquery-update-10/) for specifying XML patches? It’s already standardized syntax and there are several implementations including open-source ones.

JSON-LD at least allowed for a JSON all the way down idea, updates not an issue of API but merely the cognizance to address the proper ReSTful resource. Let me expand on your example:

{ “name”: {“@id”: “/widgets/abc123/name”, “@value”: “abc123”} “colour”: {“@id”: “/widgets/abc123/color”, “r”: {“@id”: “/widgets/abc123/color/r, “@value”: 0}, “g”: {“@id”: “/widgets/abc123/color/g, “@value”: 0}, “b”: {“@id”: “/widgets/abc123/color/b, “@value”: 255}, “count”: {“@id”: “/widgets/abc123/count”, “@value”: 4} }

To use:

PUT /widgets/abc123/color/g 255

PUT /widgets/abc123/count 5

Here JSON declares addresses for sub-resources; no new APIs need to be concocted to update a sub-resource, we’re free from /widgets/abc123?action=incrementCount. Rely upon ReSTful objects that weave the web of data about them.

I wish I could say I like JSON-LD, because with regards to creating a web of data I am zealously in favor of the plan. And JSON-LD gets most things right. With lamentation, I find the text of the Syntax specification and the entirety of the API specification to be regrettably if not criminally pedantic arm-twisting and hideous: I am in their choir, I already believe, and it’s all I can do to make out what they’re saying, the signal noise is overwhelming, originating from discussion of legacy topics like RDF. In spite of finding the specifications largely incomprehensible, the example I jotted down above demonstrates something rather pure, models what resourceful ought to mean on the web, and I wish JSON-LD the best.

W/r/t JSON Patch;

My primary interest in JSON Patch is atomicity: I can throw 300 different resource PUT requests at a server, but there are not great tools for coordinating those requests, nor for making sure my requests dont start interleaving reqeusts with someone else’s ongoing updates. JSON Patch can return a nice easy identifier for an entire slew of changes, which is fantastic.

Glad to see Rob Sayre’s old post continuing to pick up steam; thanks James Clark for helping take up the cause.

Easy to get me going on these topics, hope that’s ok. Looking forwards to the day when I can make the time to get my streaming-data Arclamp project back under way, JSON-Patch was one of the biggies I wanted to tack to. Thanks mnot.

JSON-Ref is more about pulling in other external data-elements than it is defining resourceful addressing, but it too could serve as a lighter-weight version of JSON-LD’s “@id”, and not take up so much semantic baggage. The unifying theme of making sub-resources their own first class resource is capital.

I have been using a simple [patch][add /][replace /][remove /][/patch] format for a couple years (no support for move, copy, or test). I have been standing down while the JSON effort completes.

While non-trivial, I think it reasonable to pick up the work on an XML Patch diff format once JSON-Patch goes RFC.

You might be interested in the small section 7.5.2 “patching resources” of my bachelor thesis. I saw three problems with PATCH:

No mediatypes for patch - Thank you for working on this! No means to indicate the representation of a resource against which the patch should be applied More philosophical: Is patch still rest since no full representation is submitted?

Example for the second point: A contact manager serving the portable contacts json format and a future vcard+json format. On receiving application/json-patch, which one should be the target of the patch?

I’m looking forward to your comments!

Regarding atomicity, one option would be to make conditional requests (If-Match). In the text world, the unified diff format carries optional context with it so that it’s easier to understand where/if the patch can be applied. What might the json-patch equivalent to context look like?

Hi Mark,

I’ve already tried to post that to ietf-types but apparently the list was renamed to media-types and I haven’t been signed up yet.

So I’ll ask it again here:

Why did you choose application/json-patch as media type instead application/patch+json?

How would this be able to replace your incrementCount example, in a trivial case like two browsers visiting the same resource, each merrily clicking a “Like” button? Say, with an original state of “0 likes”, two clicks in browser A (making it “2 likes”) followed by one click in browser B (making it “1 like”, not the “3 likes” we want).

As I read it, PATCH would only be useful for specific cases where the object being edited has no internal consistency constraints (i e where it’s for some reason known that blindly overwriting one property always is a legal and safe operation, no matter what state that resource was in), or where you for some reason are certain that your current request has a server-global lock on the resource and that the client’s idea of the object state is identical to the server’s.

Am I missing something?

Mark,

I find partial updates (and batched requests) are a common problem in HTTP that lead most RESTful designs to end up as RPCs! So, thank you for working on this.

I see that your model can be easily used to patch other mediatypes too, using json for the patch format. E.g., allowing xpath selectors in place of the json-pointer and accepting json-encoded xml fragments for the values should allow updates to xml mediatype resources. You may have to extend your model a bit to address attributes and namespaces.

In general, you should be able to define a generic patch format that can be used to partially update resources in any mediatype so long as the resource mediatype defines a mechanism to identify fragments. In practice it may turn out that these two are often the same or very similar, but they need not be. And, there can be cases where they can not be the same, e.g. text/plain.

As an example, given the document

foo bar baz

the patch instruction

[ { “add”: “char=4”, “value”: “qux “ } ]

changes the document to

foo qux bar baz

You need to provide a mechanism to choose a specific representation of the target resource (also pointed out by Thomas above), and that may be used to interpret the semantics of the fragment identifier.

Out of curiosity, what do you make of this syntax https://github.com/algesten/jsondiff vs JSON PATCH?

Could you use XSLT as a media type for PATCHing an XML representation?

The counterpart of PATCH would be a DIFF method. In my use case I have a long list of thousands of (JSON) objects that users need to download completely (I’m talking MBs of data here). Only a few objects change every day. Always having to download the whole list on every change (GET + If-None-Match) is slow and wasteful.

That’s where DIFF (and some new header like ‘Base-ETag’ or so, specifying the ETag the diff is based upon) would come in handy. Obviously the server might not want to keep the whole history, in cases where the base version is not available any more (or if the given ETag never existed) I guess it would be a ‘412 Precondition Failed’ and the client would have fall back to GET + If-None-Match.

Although PATCH is mentioned in a number of RFCs, DIFF seems to be of much less interest. I wonder why that is… Has anyone of you guys that looked into PATCH also contemplated the DIFF counterpart?

Hi Mark,

How fully supported is PATCH on existing web servers, routers and other middleware? I’m concerned the web might need to be upgraded globally for this to work reliably in all cases? But I guess I can see it’s value in supporting multiple operations per HTTP request.

Anyway, it’s a shame that the following PUT:

PUT /order/12345/status

shipped

Doesn’t get reflected in the cached representation of the following:

GET /order/12345

Do you know if anyone considered as an option/addition to PATCH to add a PATCH-{op} header to specify the parent URL and the child path, i.e.

PUT /order/12345/status PATCH-REPLACE /order/12345, /status

shipped

Would that work? Pros, cons?

-Mike

Has any work been done to support patching with binary data? I do not mean patching parts of a binary document, but rather being able to replace a binary document as part of a patch document?

Example:

[ { op: “replace”, path: “/Document”, value: … binary data … } ]

This may though be more of a JSON than PATCH question, but perhaps some thought has been given to this already?

We have been considering two different solutions: 1) encode binary data as BASE64 and send it as a string, or 2) expose the binary document data as a separate resource which can be updated separately.

The BASE64 solution carries some overhead in the payload size, and the separate resource solution makes it impossible to do atomic/transactional updates of both the binary document data and related meta data in one single request. So neither are perfect.

Thanks, Jørn

I’m a bit surprised that the proposal is to bind the concept of partial updates to another HTTP method. None of the other methods dictate the style of the message to this degree. Couldn’t this be just be part of future media types? I realize that there is value in establishing a widely adopted convention but it just seems too specific to have it’s own method when POST seems adequate.

It’s one thing to think about how a general transformation could be applied on the server but how do you communicate to the client the affordances for PATCH? The templates for what can be changed and what can’t? Is this not specific to the domain.

Also if we are really doing Information Technology then while the consumable representation may appear as if state has been removed, replaces etc… in many cases we, at least should be, processing these types of messages in an event sourcing way. i.e. we continuously ADD revisions to a resource in which case the concept aligns perfectly with POST.

Tim Stokes

What I mean is that it’s too representation orriented to have a general way to transform PATCH messages while I don’t want to loose the resource orriented context of the HTTP methods. I POST state to my “resource” not a representation because the representation is decided by content negotiation. In fact my core business as a service is choosing how the posted state changes variouse representations of my resource. I don’t see the value in a generic transformation model.

PATCH seems like its focusing on the representation rather than the abstract concept of the resource which is very important to me.

REST components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types, selected dynamically based on the capabilities or desires of the recipient and the nature of the resource. Whether the representation is in the same format as the raw source, or is derived from the source, remains hidden behind the interface.

If anybody is interested, I made a new Javascript implementation (based on DRAFT 10) that focuses on footprint and performance (1.6 KB). It support applying patches to object trees.

I am currently adding a patch generator for outgoing patches (using ES6 Object.observe() or dirty checking A observe() is currently only in Chrome 27)

Hi Mark. I thought I ought to point out to your readers that this format may be overkill for many simple resources. Service designers should be kept in mind that a server can always accept x-www-form-urlencoded as a media type too!

The example you give would then just be:

PATCH /widgets/abc123 HTTP/1.1 Host: api.example.com Content-Length: 7 Content-Type: application/x-www-form-urlencoded

count=5

By using this, it is easy to make the server compatible with POSTs from HTML forms using a method override parameter:

POST /widgets/abc123 HTTP/1.1 Host: api.example.com Content-Length: 21 Content-Type: application/x-www-form-urlencoded

count=5&_METHOD=PATCH

My own intranet application uses this principle to support AJAX where available and fall back to UA default implementations otherwise. This way we get the semantics of HTTP as best supported by the client, and it’s easy to have a single implementation at the back end that routes POSTs with an _METHOD parameter to the handler for the method specified.