HTTP,

REST 

and the PATCH verb

(accompanied by kittens)

Thomas Parslow@almostobsolete

http://almostobsolete.net

Web services

The web is used by machines as well as humans

Web services are like web sites for machines

Various ways to design web services

RPC

SOAP (please no)

HTTP is awesome!

Simple

Common set of operations

Libraries in every language

Compression?

Encryption?

Cacheing?

Http has got it covered...

REST

Think in nouns not verbs!

Resources are nouns

Resources are addressable and linked

http://example.com/blogpost/1

NOT: http://example.com/get_blogpost

Current main HTTP verbs

GET PUTDELETE POST

Show!Replace! Destroy! Do stuff!

Why REST?

Trendy buzzword

Discoverable, self describing APIs

Less special cases and one offs

More maintanable

Less code!

Real world example: Telephone conference control

Conference

Caller

Get conference details (GET)Lock/UnlockRecord On/ Record OffEnd conferenceAdd caller (dialout)Get List Of Callers

Evict callerMute CallerUnmute caller

Conference{  "type": "conference",  "href": "http://example.com/conferences/1",  "head": {    "allow": [ "GET", "DELETE", "PUT", "PATCH" ],    "created_at": "2011-10-21T10:56:54Z",     "related": {      "callers": {"href": "http://example.com/conferences/1/callers"}  },  "body": {    "recording": false,    "locked": false  }}

Caller List{  "type": "caller-list",  "href": "http://example.com/api/v1/conferences/1/callers",  "head": {    "allow": ["GET", "POST"]  },  "body": [    {"href": "http://example.com/conferences/1/callers/1"}  ]}

Caller{  "type": "caller",  "href": "http://example.com/conferences/1/callers/1",  "head": {    "allow": [ "GET", "DELETE", "PUT", "PATCH" ]  },  "body": {    "phone_number": "07951261227",    "name": "Tom",    "type": "chair",    "muted": false  }}

Real world example: Telephone conference control Conference

Caller

Real world example: Telephone conference control

Conference

Caller

Get conference details (GET)Lock/Unlock (PUT)Record On/ Record Off (PUT)End conference (DELETE)

Get caller details (GET)Evict caller (DELETE)Mute Caller (PUT)Unmute caller (PUT)

Caller ListGet list of callers (GET)Add caller (dialout) (POST)

Partial updates

  WHY?

Efficiency: Large resources

Concurrency: Multiple people changing at once

  Approaches used:

Overloaded POST - One of operations are bad :(

Split up resource - End up with unnatural resource divisions

The PATCH Verb

New HTTP verb

Partially updates a document

Neither idempotent nor safe

Patch format unspecified

http://tools.ietf.org/html/rfc5789

JSONPatch   

A patch format for JSON documents

http://tools.ietf.org/html/draft-pbryan-json-patch-0

 [ { "remove": "/a/b/c" },

 { "add": "/a/b/c", "value": "foo" }, { "replace": "/a/b/c", "value": "bar" }

 ]

My new Javascript JSONPatch implementation!

https://github.com/dharmafly/jsonpatch.js

Thanks for listening!

Questions?

@almostobsolete