...now I work here...
(and I brought give-away readers)
Slide 4
Slide 4 text
Representational State Transfer
Slide 5
Slide 5 text
Representational State Transfer
Slide 6
Slide 6 text
REST
Slide 7
Slide 7 text
RESTful
Slide 8
Slide 8 text
HTTP
Slide 9
Slide 9 text
means of
INTEGRATING
disparate stuff
Slide 10
Slide 10 text
(my DARK and shameful PAST)
* 4 years of:
** IBM WebSphere
** ESB
** SOAP/WSDL
** Enterprisey
* REST vs SOAP vs HTTP vs JMS vs WMQ vs PUB/SUB vs EDA vs HA vs D/R
Slide 11
Slide 11 text
INTEGRATIONs
Slide 12
Slide 12 text
APIs
Slide 13
Slide 13 text
INTERFACEs
Slide 14
Slide 14 text
UNIFORM
* REST defines a uniform interface
* As opposed to SOAP, CORBA, etc
Slide 15
Slide 15 text
GET
PUT
POST
DELETE
- list all foo
- 501
- create a new foo
- 501
a/b/c/foo
Slide 16
Slide 16 text
GET
PUT
POST
DELETE
- details of {id}
- update the {id}
- 501
- delete the {id}
a/b/c/foo/{id}
Slide 17
Slide 17 text
VERBs
Slide 18
Slide 18 text
(OPTIONS)
* not common (yet)
* mention: pre-flight
Slide 19
Slide 19 text
GET
* retrieve
Slide 20
Slide 20 text
HEAD
* retrieve without content (ie metadata)
Slide 21
Slide 21 text
POST
* create (without known id) or update (with/without - unsafe)
Slide 22
Slide 22 text
PUT
* update or create with known id (idempotent)
Slide 23
Slide 23 text
DELETE
* remove
Slide 24
Slide 24 text
(TRACE)
* ?
Slide 25
Slide 25 text
(CONNECT)
* ?
Slide 26
Slide 26 text
IDEMPOTENT
* Without side effects
* Fine to call multiple times
Slide 27
Slide 27 text
safe idempotent unsafe
OPTIONS X (x)
GET X (x)
HEAD X (x)
POST X
PUT X X
DELETE X X
TRACE X (x)
CONNECT
Slide 28
Slide 28 text
DEVELOPing
Slide 29
Slide 29 text
WELL BEHAVED
* be well behaved
* read up on HTTP/1.1
Slide 30
Slide 30 text
ETag
* The most overlooked HTTP header in API design?
Allows concurrency control
* if-match: “”
* if-none-match: “”
* 304 not modified
* version number
Slide 31
Slide 31 text
VARY
* Tell clients/caches which headers that forms the response (ie what’s the cache-combo)
* ie: Vary: Accept ( /foo/bar vs /foo/bar : XML vs JSON)
Slide 32
Slide 32 text
CACHE-CONTROL
* age
* no-cache
* no-store
Slide 33
Slide 33 text
EXPIRES
* Expire any cached copies after...
Slide 34
Slide 34 text
BENEFITs
Slide 35
Slide 35 text
CLIENTS
PROXIES
SERVERS
LOAD BALANCERS
* will all understand and act accordingly
* in addition cool modern software does HTTP/REST out-of-the-box (CouchDB, Riak)
Slide 36
Slide 36 text
PLANNING
Slide 37
Slide 37 text
URLs
* What will your URL scheme look like
* How will it evolve
* Identify natural points of extension/evolution
Slide 38
Slide 38 text
DNS
* This is part of your URL
* Think about partitioning (subdomains)
* Think about future transition, separation, isolation
* Does Wildcard DNS make sense to you?
Slide 39
Slide 39 text
SECURITY
* HTTPS + basic auth (one stop shop)
* API auth (client certificates, OAuth)
* SSL cookies
CONTRACTS
* What do we promise our clients?
* Read these:
- http://martinfowler.com/bliki/TolerantReader.html
- http://martinfowler.com/articles/consumerDrivenContracts.html
Slide 65
Slide 65 text
SERIALIZED
FORM
+ Easy programming (initially, typed proxies)
- Rigid (will not bend, will break)
Slide 66
Slide 66 text
SCHEMAS
* Good for automated testing
* If you give them away, assume people will generate proxies (and depend on serialized form)
* Consider not providing any (or model them loose, xs:any etc - I’m not sure it’s a good idea)
Slide 67
Slide 67 text
GUARANTEES
* Fields annotated with “#userid” will have the following form
* Attributes named “email” will conform standard X
* This document contains one, and only one field annotated “#id”, which is the unique id for
Y