When a client changes only one part of the resource, you can optimize the entire update process by allowing the client to send only the modified part to the server, thereby saving the bandwidth and server resources. RFC 5789 proposes a solution for this use case via a new HTTP method called PATCH. To learn more about this RFC, visit https://tools.ietf.org/html/rfc5789. Note that PATCH is not yet officially a part of HTTP/1.1. However, the HTTP protocol allows both the client and the server to implement any new method. Leveraging this flexibility, many vendors have started supporting the HTTP PATCH method.

The PATCH method takes the following form:

PATCH /departments/10 HTTP/1.1 
[Description of changes] 

The [Description of changes] section, in the preceding PATCH method, contains instructions describing how a resource currently residing on the origin server should be modified in order to reflect the changes performed by the client. RFC 6902 defines a JSON document structure for expressing the sequence of changes performed on the resource by the client. Note that you can also have the XML structure for describing the changes performed on the XML representation of the resource. We are not covering the XML-based description in this book, because most of the RESTful web APIs currently use the JSON format for representing resources. You can learn more about RFC 6902 at https://tools.ietf.org/html/rfc6902. The PATCH operations supported by JSON PATCH are add, remove, replace, move, copy, and test.

The following example illustrates how you can use JSON PATCH for describing changes performed by a client on a department resource.

As the first step, the client retrieves the department resource from the server that looks like the following:

{"departmentId":10, "departmentName":"Administration", 
   "managerId":200, "comments":"Administrative works" }

The client then performs the following modifications on the department resource:

• Modifies the manager by setting managerId to 300
• Adds a new locationId=1200 value to the department resource
• Removes the comments attribute

The JSON PATCH request body containing the preceding changes will look like the following:

PATCH /departments/10 HTTP/1.1 
[ 
  { "op": "replace", "path": "/managerId", "value": 300 }, 
  { "op": "add", "path": "/locationId", "value": 1200 }, 
  { "op": "remove", "path": "/comments" } 
] 

The server applies the data manipulation instructions present in the incoming JSON PATCH document and modifies the original resource to reflect the changes performed by the client. After applying the modifications, the department resource on the server will look like the following:

{"departmentId":10, "departmentName":"Administration", 
   "managerId":300, locationId=1200}

Currently, neither JAX-RS 2 nor Jersey support PATCH out of the box. However, JAX-RS allows you to add support for the new HTTP methods via the javax.ws.rs.HttpMethod annotation. To learn how to enable the complete support for the HTTP PATCH method in your JAX-RS application, refer to the Appendix of this book.