Navigation Menu

Skip to content

Instantly share code, notes, and snippets.

@kevinswiber

kevinswiber/thoughts.md

Created November 6, 2013 08:35
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 2 You must be signed in to fork a gist
  • Save kevinswiber/7332789 to your computer and use it in GitHub Desktop.
Save kevinswiber/7332789 to your computer and use it in GitHub Desktop.
Download ZIP
Some thoughts on RFC 6902 - JavaScript Object Notation (JSON) Patch
Raw
thoughts.md

Thoughts on JSON Patch

Introduction

JSON Patch is a media type developed to take advantage of the HTTP PATCH method. It includes operations such as add, remove, replace, copy, move, and test. Below is a first reaction to reading the specification. Note that the author has not attempted a real implementation of JSON Patch, which would certainly provide a more thorough analysis and different perspective.

Benefits

  1. The JSON Patch specification provides an actual media type to use with PATCH. This enables the PATCH method to be usable across client-server implementations. It's a real attempt at solving the partial update problem in Web APIs.
  2. JSON Patch documents allow shallow and nested object updates.
  3. The format allows appending to arrays, either by index or by specifying a "-" to push the value to the end of the array. The latter is very helpful for large array structures and allows clients to send patch requests without first retrieving an array count.
  4. Priority and order of operations is clearly defined. Operations are executed top-down. Operations are executed against the previous version of the resource combined with any previously successful operation included in the patch request.
  5. Via the HTTP PATCH RFC, patches are defined as being atomic. It's helpful if the property of atomicity is consistent across implementations.

Issues

  1. There isn't a way to specify a representation being updated. Therefore, the format implies patches are for an underlying resource model. This requires exposing server internals to clients and may hinder benefits of independent client-server evolution. For implementations that have a single, JSON-based resource representation, this is less of a problem initially, but it may become a problem if the server wishes to take on new media types in the future (application/xml, application/vnd.siren+json, text/html, etc.)
  2. It may be difficult for clients to determine which operation is intended. If a UI (such as from a mobile app) is guiding the generation of patch documents, the client needs a way to determine which operation is intended before generating the JSON Patch request (i.e., is it a move, replace, copy or a combination of add and remove?)
  3. The server may find it difficult to glean intent from JSON Patch documents. This impacts calls to an underlying domain model on the server if one exists. For auditing, audit logs would have to be generated from JSON Patch requests, which may suffer some of the same issues with intent discovery.
  4. The problem of "replace value with null" vs. "remove property altogether" may still exist in some cases.
  5. Error handling for large patch operations may be difficult to debug. There's no specified format for error responses. (Should a stack trace exist to communicate which operation failed and why?) This makes it difficult to inform clients how to recover from error responses.

References

@Uzlopak
Copy link

Uzlopak commented May 3, 2020

There's no specified format for error responses.

See https://tools.ietf.org/html/rfc7807

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment