4

Here is what RFC 5789 says:

The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request-URI. The set of changes is represented in a format called a "patch document" identified by a media type. If the Request-URI does not point to an existing resource, the server MAY create a new resource, depending on the patch document type (whether it can logically modify a null resource) and permissions, etc.

The difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the resource identified by the Request-URI. In a PUT request, the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version.

Let's say I have { "login": "x", "enabled": true }, and I want to disable it.

According to post "Please. Don't Patch Like An Idiot.", the proper PATCH request would be

[{ "op": "replace", "path": "/enabled", "value": false }]

However, let's take this request:

{ "enabled": false }

It also 'contains a set of instructions describing how a resource currently residing on the origin server should be modified', the only difference is that JSON property is used instead of JSON object.

It seems less powerful, but array changes can have some other special syntax if required (e.g. {"a":{"add":[], "remove":[]}}), and server logic might not be able to handle anything more powerful anyway.

Is it an improper PATCH request as per RFC? And if so, why?
And, on the other hand, would a { "op": "disable" } be a correct PATCH request?

Community
  • 1
  • 1
Andrey Shchekin
  • 21,101
  • 19
  • 94
  • 162

1 Answers1

2

the only difference is that JSON property is used instead of JSON object.

It's actually a bit deeper than that. The reference to RFC 6902 is important. The first request has a Content-Type of application/json-patch+json, but the second is application/json

The important thing is that you use a 'diff media type,' one that's useful for this purpose. You don't have to use JSON-PATCH, (I'm a big fan of json-merge-patch), but you can't just use anything you want. What you're asking about in the second part is basically 'can I make my own media type' and the answer is 'yes,' just please document it and register it with the IANA.

Community
  • 1
  • 1
Steve Klabnik
  • 14,521
  • 4
  • 58
  • 99
  • I see your point, but on the other hand the type for my entities themselves (e.g. for `POST`/`GET`) is not registered with IANA. Currently I am using `application/json`, but I could use `application/vnd-user+json` for `POST`/`GET` and then `application/vnd-user-partial+json` for `PATCH`. Why is `PATCH` different from `POST`/`GET` and why does it need a more formal type? – Andrey Shchekin Sep 09 '14 at 23:47
  • They are registered, you're serving them as application/json. The important difference is that POST and GET say nothing about what their content type must be, but the definition of PATCH does. It needs that requirement because it's inherent to how PATCH works: by making changes of some kind. – Steve Klabnik Sep 09 '14 at 23:50
  • and if you did that, then `application/vnd-user-partial+json` (though it should really be `application/vnd.user-partial+json`) is the custom type that I mentioned. – Steve Klabnik Sep 09 '14 at 23:51
  • _The important difference is that POST and GET say nothing about what their content type must be, but the definition of PATCH does._ RFC 5789 does not force RFC 6902 though? E.g. if I used XML everywhere my PATCH would definitely not be RFC 6902, yet still be _a a set of instructions_. – Andrey Shchekin Sep 10 '14 at 00:10
  • Yes, it only does if you're using JSON. If you're using XML, then you'd be using a different diff format. – Steve Klabnik Sep 13 '14 at 13:30