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!
introduction to json patch
By warpech
introduction to json patch
- 5,634