RFC-6902 based HTTP Patch Operation on JSON Objects

Photo by gustavo Campos on Unsplash

Introduction:
Hypertext Transfer Protocol (HTTP) defines a set of request methods AKA HTTP verbs to indicate the desired action to be performed for a given resource. Some of the most common methods are GET, PUT, POST and DELETE. While most software engineers are well aware of the characteristics of these 4 methods, sometimes a situation arises when we need to look beyond, i.e., use methods like PATCH, HEAD etc.

HTTP PATCH Operation:
The HTTP PUT method is used to overwrite a resource with a complete new body, and cannot be used to do partial changes. To overcome this limitation and apply partial modifications to a resource, the HTTP PATCH request method was introduced in RFC 5789.

The HTTP PATCH executes the requested changes atomically. It means that if the server can’t satisfy all the requested changes, it doesn’t modify the target entity.

PUT vs PATCH Dilemma:
As per the definition, the PUT method replaces all current representations of the target resource with the request payload, while the PATCH method applies partial modifications to a resource. It can be understood that both PUT and PATCH are somewhat analogous to the update concept found in CRUD, but the main difference is: PATCH request is considered a set of instructions on how to modify a resource. Contrast this with PUT; which is a complete representation of a resource.

RFC-6902:
There are myriad examples over internet on how the PATCH operation can be used in a simple way. But specially, when we talk about modifying a JSON resource, we often overlook below fact stated in RFC-5789:

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.

In simpler words, the RFC-5789 says that in the request body, we need to specify a set of actions or instructions to modify the current resource. So how do we set the actions in the request body? How should we format it?

This is exactly where RFC-6902 comes to rescue. This specification talks about how the set of instructions can be sent using JSON Patch format for partial update to a resource. JSON Patch is a format for expressing a sequence or array of operations to apply to a target JSON document through the HTTP PATCH method.

Each operation object in the request body consists of 3 main attributes:
[0] op — indicates the operation to perform. As per the specification, its value MUST be one of “add”, “remove”, “replace”, “move”, “copy”, or “test”
[1] path — string containing a JSON-Pointer value that references the “target location” where the operation is performed
[2] value — data to be operated for the given path

Consider below simple JSON:

GET marvel/avengers/1
{
 "name": "Tony Stark",
 "address": "Malibu Point"
}

Let’s assume that we want to change the address attribute through PATCH operation. Usually, we would send the HTTP PATCH request as below:

PATCH marvel/avengers/1
{
 "address": "Stark Tower LA",
 "addressType": "office"
}

But in the above request, we are not specifying the instruction. If we want to send request as per RFC-6902, PATCH request would look like below:

PATCH marvel/avengers/1
[
 {
  "op": "replace",
  "path: "/address",
  "value": "Stark Tower LA"
 },
 {
  "op": "add",
  "path: "/addressType",
  "value": "office"
 },
]

Considering above operation is successful, we will get the modified object as below:

GET marvel/avengers/1
{
 "name": "Tony Stark",
 "address": "Stark Tower LA",
 "addressType": "office"
}

Conclusion:
RFC-6902 states that:

JSON Patch is a format (identified by the media type “application/ json-patch+json”) for expressing a sequence of operations to apply to a target JSON document; it is suitable for use with the HTTP PATCH method.

Thus, the correlation between RFC-5892 and RFC-6902 can be understood in simple words, i.e., we can use JSON-PATCH as the request-body on the HTTP-PATCH request method.

Additionally, the advantages of using JSON-PATCH can be observed when
- we have to deal with a complex JSON structure having a deep hierarchy of attributes
- we need to restrict the user and allow only selective fields to be patched