Introduction to

json patch





Marcin Warpechowski (@warpech)

8th Munich Node.js User Group Meetup

April 11th, 2013 

problem


You want to compare 
two JSON documents

You want to apply a partial update
to one of them

specific problem


You need a way to transport data 
from single page application 
(client) to server

So you spend half of the 
development time 
building the API





REST IS hard


you want it lean


JSON PATCH

Lightweight, standarised way of sending 
changes to JSON documents

Document:
{
  "name": {
    "first": "Marcin",
    "last": "Warpechowski"
  }
  "pets": []
}

Patch:

{"op": "add", "path": "/pets/0", "value": "dog"}

json patch

Lightweight, standarised way of sending 
changes to JSON documents

Document:
{
  "name": {
    "first": "Marcin",
    "last": "Warpechowski"
  }
  "pets": ["dog"]
}

Patch:

{"op": "add", "path": "/pets/0", "value": "dog"}

BASIC OPERATIONS

  • test - check if path has given value
    {"op": "test", "path": "/a/b/c", "value": "foo"}


  • remove - remove path
    {"op": "remove", "path": "/a/b/c"}


  • add - insert new value at path
    {"op": "add", "path": "/a/b/c", "value": ["foo", "bar"]}


  • replace - replace value at path
    {"op": "replace", "path": "/a/b/c", "value": 42}


syntactic SUGAR OPERATIONS


  • move - take some node from the JSON document and put it in different place (same as remove + add)
    {"op": "move", "from": "/a/b/c", "path": "/a/b/d"}
  • copy - clone a node inside the JSON document (same as add, but uses from instead of value)
    {"op": "copy", "from": "/a/b/d", "path": "/a/b/e"}

http patch

JSON Patch was designed to work with HTTP PATCH
So your server knows when you are sending a patch

PATCH /my/data HTTP/1.1
Host: example.org
Content-Length: 318
Content-Type: application/json-patch+json
If-Match: "abc123"

[
  {"op": "test", "path": "/a/b/c", "value": "foo"},
  {"op": "remove", "path": "/a/b/c"},
  {"op": "add", "path": "/a/b/c", "value": ["foo", "bar"]},
  {"op": "replace", "path": "/a/b/c", "value": 42},
  {"op": "move", "from": "/a/b/c", "path": "/a/b/d"},
  {"op": "copy", "from": "/a/b/d", "path": "/a/b/e"}
]

WHAT IS IT GOOD FOR

  • SPA (single page applications)
  • MVP (minimum viable product)
  • stateful applications (where data on client reflects data on server)
  • single place (server) input validation
  • real time collaboration on documents
  • multi-user games
  • offline data synchronization
  • other applications that make little changes in big documents
  • plays nice with HTTP PATCH and Web Sockets

WHAT is it bad for

  • does not replace REST - to make a full API that will be useful to 3rd parties, you still need to support standard HTTP verbs GET, PUT, POST, DELETE

  • JSON Patch exposes whole document for changes - you need to perform access control and data validation before you apply the patch

What is ready


  • Released in April 2013:
    - RFC 6902 for JSON Patch
    - RFC 6901 for JSON Pointer (which is the "path" part in JSON Patch)
  • Client libraries in JavaScript and many other languages
  • Already works in all browsers (including IE)

WHAT IS MISSING


  • Some client libraries are unoptimized or refer to old version of the RFC draft

  • No good JSON Diff solution. You are responsible to observe your JSON document for changes (can use Object.observe from ECMAScript Harmony)

  • Frameworks and databases don't leverage it yet. Would make a neat interface to (No)SQL databases

Use it already and contribute to the community!

resources

    RFCs
JSON Patch:   
    http://tools.ietf.org/html/rfc6902
JSON Pointer: 
    http://tools.ietf.org/html/rfc6901
HTTP PATCH:   
    http://tools.ietf.org/html/rfc5789
    Implementations
JS (Node.js): 
    https://npmjs.org/package/json-patch
JS (browser & Node.js): 
    https://github.com/Starcounter-Jack/Fast-JSON-Patch


    More reading
    http://www.mnot.net/blog/2012/09/05/patch
    Photo credits
    http://www.flickr.com/photos/ifl/5324565888/
    http://commons.wikimedia.org/wiki/File:Dekotora.jpg

Thanks!


Made with Slides.com