JSON Merge Patch

Usually, responses to endpoint calls made to our APIs are returned in JSON. JSON (JavaScript Object Notation) is a lightweight data-interchange format that makes it easy for you to read and write and for our systems to parse and generate responses to your API calls.

As your solutions interact with our system via endpoint calls, the need to update and modify JSON objects returned becomes increasingly common. Patching information in our system usually comes with the need to update or fix information lapses or outdated pieces of information that have been onboarded into our system.

Because of this, we have adopted an easy way of patching information in our system. The method we have adopted is the JSON Merge Patch.

📘

Other Patching Methods

There are other methods of information patching. However, our system uses the JSON Merge Patch for information patching.

What is JSON Merge Patch?

JSON Merge Patch is a simple approach specification that provides a means to describe a series of modifications to a JSON document. This implies that there is an original JSON document to be modified. However, to be modified, a JSON Merge Patch document uses a syntax similar to the original JSON document describing the changes to be made. When the Merge Patch is added to the original document, it results in a modified version.
Unlike the more detailed JSON Patch, which provides a series of operations to apply (like add, remove, replace), JSON Merge Patch is a more straightforward approach that represents the changes directly.

How Does JSON Merge Patch Work?

To apply a JSON Merge patch, you take a source JSON document and a merge patch document. The result is a new and modified JSON document. The JSON Merge Patch works as follows:

Overwriting Values

Usually, JSON response documents express responses as an Object. These objects have members which contain different data fields. If the Merge Patch document includes a member with a non-null value, the member's value in the target JSON document is either added (if not already present) or replaced (if it exists). As a result, you can set or modify new values by defining them in the Merge Patch.

Removing Members

If the Merge patch contains a member with a null value and that member exists in the original document, the member is removed from the original JSON document. Some items can be marked in documentation as Required; thus, in this case, they are required when added to JSON. If they are not added in JSON (with null), then they are not required because they will not be changed.

Recursion for Objects

If the merge patch contains a nested object and the original JSON document has a member with the same name, the algorithm is applied recursively to both.

Array Handling

If the merge patch has an array, the whole array in the target (if it exists) is replaced by the new array. However, JSON Merge Patch doesn't support array-specific operations (like append, insert, or remove a specific item). The entire array gets replaced with a new one.

JSON Merge Patch Use Cases in our System

In our system, you can use JSON Merge Patch with any PATCH method that calls specific endpoints in our API. This combination provides an efficient way to modify existing information without requiring you to send the whole updated information.

To use JSON Merge Patch with a PATCH request in our API, please note the following:

Request Method

You can only use JSON Merge Patch with the PATCH method in our system. This signals our system that a partial update of the existing information is intended.

Content-Type Header

When making your PATCH request, include the Content-Type header with the value application/merge-patch+json. This indicates to our system that the information you are sending contains a JSON Merge Patch document.

Request information

The body of the PATCH request should contain the JSON Merge Patch document that describes the changes to be made to the original information.

Processing

Our system's API will read the existing information, apply the merge patch, and then save the modified data. If the information does not exist in the system, it returns a 404 Not Found error status. However, if the merge patch document is invalid or cannot be applied to the resource, our system responds with a 400 Bad request error status.

Response

After a successful merge patch, our system may respond with a 204 No Content status to indicate that the information was successfully updated without returning any content. Alternatively, our system may return with a 200 OK status and the modified resource in the response body.

For Example

The image below is a company already onboarded into our system named "Kayode's Holdings."

You then set the Content-Type header to application/merge-patch+json.

You then attach the JSON Merge Document to the request body and make the PATCH request to our API. The call returns the modified document and a 200 OK status response code to indicate that the Patch has been done.

Best Practices

To maintain a robust, efficient, and secure system when using the JSON Merge Patch in our system, it is necessary to adhere to some of the best practices, which include the following:

Content-Type Header

Ensure you set the Content-Type Header to application/merge-patch+json to indicate that the request data contains a JSON Merge Patch document.

Validation

Ensure you validate the merge patch document before applying it to the original document to ensure it adheres to the expected format and is devoid of malicious data.

Avoiding Array Manipulations

JSON Merge Patch does not support certain array operations like removing or adding specific items. Thus, avoid making such patches in our system, although there is already minimal need for such operations.

Conclusion

JSON Merge Patch is a straightforward and intuitive protocol for describing modifications to a JSON document. It offers an efficient means to represent changes, making it particularly valuable for systems and applications where partial updates are standard, such as our API using the PATCH method.

By providing a simple way to overwrite values, remove members, or update nested objects, it streamlines the process of updating JSON data structures without the need to resend the entire document.