What's the proper URL structure in REST API for changing state of one particular record (e.g. change from "new" to "processed").

Now I work with this URL without request body:

PATCH /employees/123/items/456/process/ HTTP/1.1

But maybe better will be:

PUT /employees/123/items/456/ HTTP/1.1

and in request body specify status:




It seems a combination of both solutions is appropriate:

PATCH /employees/123/items/456 HTTP/1.1

With a request body of:


From RFC 5789:

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. The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH.

(emphasis, mine)

  • This doesn't address more complicated cases of patch, or doesn't explicitly mention JSON PATCH (tools.ietf.org/html/rfc6902) - and isn't a proper example of JSON PATCH. – Lewis Pringle Jul 25 '18 at 13:45
  • This also doesn't address collisions. – Lewis Pringle Jul 25 '18 at 13:47
  • How does this work if you are deleting a field, or adding new members to an array? – Lewis Pringle Jul 25 '18 at 13:54

I recommend using JSON PATCH for this - https://tools.ietf.org/html/rfc6902

PATCH /employees/123 HTTP/1.1
Host: example.org
Content-Type: application/json-patch+json
If-Match: "abc123"

 { "op": "replace", "path": "/items/456/state", "value": "processed" },

There are a couple key features of this solution:

  • You can replace (or add to or delete) any part of the target object, just by addressing that part using JSONPath (like XPath) and specifying the new value. DELETE REPLACE or ADD supported (as well as others like move).

  • You CAPTURE the ETAG in the GET, and pass it along in the PATCH call (If-Match) - so that you don't apply a change to the wrong VERSION of an object (if two people make changes in the same time, the first wins, instead of the first wins and the second corrupts the data)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.