JSON Patches in REST

A JSON patch is exactly what its name suggests: a patch for a JSON document, i.e., another JSON doc describing a set of changes which are to be applied to the original JSON. JSON patch follows the RFC 6902 specification. The JSON patch specification can be readily combined with a rest interface so that clients can update their resource in part without the need to apply a PUT to re-upload the whole JSON. In this post we'll go through an application case: a RESTful web service for bibliographic entries.

Application case

The REST web interface we are describing here is designed to support a bibliography management system.

Users can register bibliographic references, access them, search through them, remove them or modify them using a JSON patch. Let's first see how a bibliographic reference looks like in JSON which can be retrieved from http://app.jaqpot.org:8880/jaqpot/services/bibtex/SopNtoSar15.

Notice that, for the sake of this example, we have deliberately omitted the conference location which is usually reported; using JSON patch we will add the additional field address to report this location.

JSON Patch in a nutshell

A JSON patch document consists of a series of modification directives which are triples which consist of (i) a modification method, (ii) the path to be modified and (iii) the value used to update the old value. JSON Patch comprises the following modification methods: add, remove, replace, move, copy and test.

A concise tutorial for JSON Patch can be found at jsonpatch.com along with other useful links. I encourage the reader to take some time to go through it.

JSON Patch in REST

In order to use the JSON patch specification in a REST framework one needs the following components:

1. A RESTful web service with JSON support
2. The HTTP method PATCH - see RFC 5789.
3. A JSON Patch engine which combines JSON documents with JSON patches to produce patched JSONs. 

We use JSON patch to apply patches which can be readily incorporated into your maven project as a dependency. Here is our pom.xml if you would like to take a look.

Clients apply the method PATCH on a resource at /resource/{id} and provide the JSON patch document specifying  Content-type application/json-patch+json. The patch is then received by the web service, combined with the existing JSON and a new updated (patched) document is created which is then stored in the database (and replaces its predecessor).

The web service, upon successful completion of the operation returns a status code 200 and the updated JSON in the response body.

The BibTeX case

Here is the BibTeX REST API:

The BibTeX REST API. Click on the image to magnify it.

Clients can list all BibTeX entries on the server (paginated), create new bibtex entries, get the representation of a bibtex entry in JSON, apply PUT or DELETE and finally, apply a PATCH as discussed before.

The PATCH API is as follows:

The PATCH API. Click on the image to magnify it.

Clients need to specify the id of the BibTeX entry they want to modify and provide, in the request body, the JSON PATCH document. Notice that the content-type is application/json-patch+json.

Let us use this interface to add an address field to the above BibTeX entry. The PATCH we have to use is as follows:

[
  {
    "op": "add",
    "path": "/address",
    "value": "Torremolinos, Spain"
   }
]

Here is the response:


As one can see, the field address has been added.

So, that's all folks... you can experiment with this interface.

This is part of the open-source project JAQPOT Quattro; you can find the source code on github.