Slide 1

Slide 1 text

PATCH & HTTP APIs

Slide 2

Slide 2 text

Honza Python API design Apiary Pyvo {…} PR API Blueprint @honzajavorek honzajavorek.cz

Slide 3

Slide 3 text

Modifying Resources { "type": "Mazda", "color": "red", "stolen": true } ! { "type": "Mazda", "color": "blue", "stolen": false }

Slide 4

Slide 4 text

Web { "type": "Mazda", "color": "red", "stolen": true } ! { "type": "Mazda", "color": "blue", "stolen": false }

Slide 5

Slide 5 text

API { "type": "Mazda", "color": "red", "stolen": true } ! { "type": "Mazda", "color": "blue", "stolen": false } PUT /car

Slide 6

Slide 6 text

Has flaws vs. Good enough • Needs recent GET on the resource. • Even with recent GET , there's obviously still race condition. • We need to send the whole resource (bandwidth). • But come on, we do this all the time with web forms…

Slide 7

Slide 7 text

Partial Update aka PATCH

Slide 8

Slide 8 text

PATCH • New HTTP method for partial updates (RFC 5789) • Body contains a description of changes. • The changes must be applied atomically by server.

Slide 9

Slide 9 text

Content-Type: my-favorite-diff-format some diff instructions PATCH /car Content-Type: application/json { "type": "Mazda", "color": "blue", "stolen": false } 200

Slide 10

Slide 10 text

Content-Type: application/json { "color": "blue", "stolen": false } PATCH /car Content-Type: application/json { "type": "Mazda", "color": "blue", "stolen": false } 200

Slide 11

Slide 11 text

Content-Type: application/json { "color": "blue", "stolen": false } PATCH /car Content-Type: application/json { "type": "Mazda", "color": "blue", "stolen": false } 200

Slide 12

Slide 12 text

application/json • Does not actually say anything about the diff format. • No shared libraries. • It is ambiguous: delete property vs. set to null? • You meet limits very soon: adding to arrays?

Slide 13

Slide 13 text

JSON Patch

Slide 14

Slide 14 text

JSON Patch • JavaScript Object Notation Patch (RFC 6902) • Way to describe changes made on JSON. • Not ambiguous, supports addressing nested structures (e.g. replacing properties of nested objects, adding to array). • application/json-patch+json

Slide 15

Slide 15 text

Content-Type: application/json-patch+json [ {"op": "replace", "path": "/color", "value": "blue"}, {"op": "replace", "path": "/stolen", "value": false} ] PATCH /car Content-Type: application/json { "type": "Mazda", "color": "blue", "stolen": false } 200

Slide 16

Slide 16 text

JSON Patch • atomic operations • path is able to address any element in JSON document • RFC is very short and half of it are examples. Just read it. • libraries…

Slide 17

Slide 17 text

• JSON Pointer (RFC 6901) • Easy to address any part of JSON document • "/pets/0" (first element in array pets) What "path"?

Slide 18

Slide 18 text

• test: check if path has given value (if not, the patch fails) • remove: remove path • add: insert new value at path • replace: replace value at path • move: remove + add • copy: clones node inside the document Operations

Slide 19

Slide 19 text

No content

Slide 20

Slide 20 text

Content-Type: application/json { "color": "blue", "stolen": false } PATCH /car Content-Type: application/json { "type": "Mazda", "color": "blue", "stolen": false } 200

Slide 21

Slide 21 text

JSON Merge Patch

Slide 22

Slide 22 text

JSON Merge Patch • RFC 7396 • Way to describe changes made on JSON. • Not ambiguous, supports addressing nested structures (e.g. replacing properties of nested objects). Replaces arrays. • application/merge-patch+json

Slide 23

Slide 23 text

Content-Type: application/merge-patch+json { "color": "blue", "stolen": false } PATCH /car Content-Type: application/json { "type": "Mazda", "color": "blue", "stolen": false } 200

Slide 24

Slide 24 text

JSON Merge Patch • standardization & exact spec of what everyone already does • very young • some libraries… • supported by orchestrate.io

Slide 25

Slide 25 text

No content

Slide 26

Slide 26 text

Misc Tricks • Return "Undo Patch" in response (or link it) to provide undo. • Conditional requests can prevent race conditions: • use If-Match headers & 412 HTTP status • PUT/PATCH exposes whole document: • use JSON Schema & 400/422 for access control

Slide 27

Slide 27 text

More • RFCs: 1855, 6902, 5789, 7396, 6901, 7230-7237, … • Misc: • http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/ • https://github.com/apicraft/detroit2013/wiki/PATCH-and-partial-updates • https://www.mnot.net/blog/2012/09/05/patch • http://jsonpatch.com/ • http://slides.com/warpech/introduction-to-json-patch#/