HTTP PATCH – Use it wisely in REST API

Nowadays, Software world is connected by APIs . Every single resource can interact with other resources by means of APIs and so they can integrate and interact with each other.Future software world would be only connected to each other by APIs to access set of their features.

There are couple of HTTP methods GET, PUT, POST, DELETE, etc by which you have developed your REST APIs. We have used PUT method to update resource on origin server 99.99% time.But according to RFC 5789, we should not use PUT method to update resource partially.

The existing HTTP PUT method only allows a complete replacement of a document.This proposal adds a new HTTP method, PATCH, to modify an existing HTTP resource.

The biggest issue with this method is either people don’t know about it or have misunderstood it(so use it in wrong way). PATCH is not strictly about sending updated value,rather than entire resource.Please do not use it like

PATCH /users/11

{ “email”: “updated.email@example.org” }

We should not send such kind of request to update email of “user” resource identified by “/users/1” request URI. In one way, instead of using PUT request with entire document(with only updated email) is more BAD than using PATCH with above request.

The official format of PATH request is with “user” example looks like

PATCH /users/11

[description of changes]

PATCH method request set of changes request[description of changes] described in the request entity, must be applied to the resource identified by the request’s URI. This set contains 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.

You can use whatever format you want as [description of changes], as far as its semantics is well-defined. That is why using PATCH to send updated values only is not suitable.You can have your framework to implement how you define description of changes and process it on origin server.The entire set of changes must be applied atomically, and the API must never provide a partially modified representation by the way.

Now the question is : Is there any official document to define set to changes ?. YES, RFC 6902 defines JSON document structure for expressing sequence of changes. This format is best to use with PATH request. It looks like

[
{ “op”: “remove”, “path”: “/a/b/c” },
{ “op”: “add”, “path”: “/a/b/c”, “value”: [ “foo”, “bar” ] },
{ “op”: “replace”, “path”: “/a/b/c”, “value”: 42 },
{ “op”: “move”, “from”: “/a/b/c”, “path”: “/a/b/d” },
{ “op”: “copy”, “from”: “/a/b/d”, “path”: “/a/b/e” }
]

It simply defines operation to be performed and specify value if needed. Email update of user resource PATCH request should be like

PATCH /users/11

[
{ “op”: “replace”, “path”: “/email”, “value”: “updated.email@example.org” }
]

If request succeeds, then it will return 200 OK in the response and 201 if new resource is created. There is another format RFC 7396 to define set to changes.It is very similar to the idea of sending only what needs to be updated, but it is explicit thanks to the application/merge-patch+json content type.

It is so readable, expressive and wonderful. This is how PATCH should be used.

It is worth mentioning that PATCH is not really designed for truly REST APIs, as Fielding’s dissertation does not define any way to partially modify resources. But, Roy Fielding himself said that PATCH was something [he] created for the initial HTTP/1.1 proposal because partial PUT is never RESTful. Sure you are not transferring a complete representation, but REST does not require representations to be complete anyway.

Useful Links

Done. If you enjoyed this post, I’d be very grateful if you’d help it spread by emailing it to a friend, or sharing it on social media. Thank you!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s