REST - Valtech

Presentation on REST given at Valtech Stockholm.

Approx 60 minutes.

Transcript

1. Hi! My name is Mårten Gustafson
2. I used to work here...
3. ...now I work here... (and I brought give-away readers)
4. Representational State Transfer
5. Representational State Transfer
6. REST
7. RESTful
8. HTTP
9. means of INTEGRATING disparate stuff
10. (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
11. INTEGRATIONs
12. APIs
13. INTERFACEs
14. UNIFORM * REST defines a uniform interface * As opposed to SOAP, CORBA, etc
15. GET PUT POST DELETE - list all foo - 501 - create a new foo - 501 a/b/c/foo
16. GET PUT POST DELETE - details of {id} - update the {id} - 501 - delete the {id} a/b/c/foo/{id}
17. VERBs
18. (OPTIONS) * not common (yet) * mention: pre-flight
19. GET * retrieve
20. HEAD * retrieve without content (ie metadata)
21. POST * create (without known id) or update (with/without - unsafe)
22. PUT * update or create with known id (idempotent)
23. DELETE * remove
24. (TRACE) * ?
25. (CONNECT) * ?
26. IDEMPOTENT * Without side effects * Fine to call multiple times
27. safe idempotent unsafe OPTIONS X (x) GET X (x) HEAD X (x) POST X PUT X X DELETE X X TRACE X (x) CONNECT
28. DEVELOPing
29. WELL BEHAVED * be well behaved * read up on HTTP/1.1
30. ETag * The most overlooked HTTP header in API design? Allows concurrency control * if-match: “<etag>” * if-none-match: “<etag>” * 304 not modified * version number
31. 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)
32. CACHE-CONTROL * age * no-cache * no-store
33. EXPIRES * Expire any cached copies after...
34. BENEFITs
35. 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)
36. PLANNING
37. URLs * What will your URL scheme look like * How will it evolve * Identify natural points of extension/evolution
38. DNS * This is part of your URL * Think about partitioning (subdomains) * Think about future transition, separation, isolation * Does Wildcard DNS make sense to you?
39. SECURITY * HTTPS + basic auth (one stop shop) * API auth (client certificates, OAuth) * SSL cookies
40. VERSIONING * This is the hard part
41. http://api.foo/v1/bar application/xml + easy (ie browser compatible)
42. http://api.foo/v1/bar application/xml - URL changes with version - Breaks the URL = resource REST thingy
43. http://api.foo/bar application/vnd.bar-v1+xml - hard (ie NOT browser compatible)
44. http://api.foo/bar application/vnd.bar-v1+xml + version is independent of URL
45. application/vnd.foo-v1+xml application/vnd.foo-v2+xml * Vary: “Accept”
46. REPRESENTATION
47. http://api.foo/bar application/xml + easy (ie browser compatible)
48. http://api.foo/bar.xml + even easier (ie really browser compatible) - more info in URL
49. http://api.foo/bar application/vnd.bar-v1+xml
50. http://api.foo/bar application/vnd.bar-v1+xml + representation is independent of URL
51. USABILITY
52. PROXIES
53. http://api.foo/v1/bar.xml
54. http://api.foo/v1/bar.xml
55. http://api.foo/v1/bar.xml http://api.foo/bar
56. http://api.foo/v1/bar.xml http://api.foo/bar application/vnd.bar-v1+xml
57. http://api.foo/v1/bar.xml http://api.foo/bar application/vnd.bar-v1+xml
58. http://api.foo/v1/bar.xml http://api.foo/bar application/vnd.bar-v1+xml
59. HATEOAS
60. WAT?!
61. LINKs * State transitions
62. MIMEs * Representations
63. LINK + MIME
64. CONTRACTS * What do we promise our clients? * Read these: - http://martinfowler.com/bliki/TolerantReader.html - http://martinfowler.com/articles/consumerDrivenContracts.html
65. SERIALIZED FORM + Easy programming (initially, typed proxies) - Rigid (will not bend, will break)
66. 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)
67. 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
68. ROBUSTNESS
69. <user> <id>1234</id> <name> <first>Mårten</first> <last>Gustafson</last> </name> </user> * XPath
70. <user> <id>1234</id> <name> <first>Mårten</first> <last>Gustafson</last> </name> </user> /user/name/last * Rigid
71. <user> <id>1234</id> <name> <first>Mårten</first> <last>Gustafson</last> </name> </user> //last * Adaptive * Might return multiple
72. <user> <id>1234</id> <name> <first>Mårten</first> <last>Gustafson</last> </name> </user> //last[1] * Adaptive * Only one
73. <user> <id>1234</id> <name> <first id=”#name.first”>Mårten</first> <last id=”#name.last”>Gustafson</last> </name> </user> * Annotated
74. <user> <id>1234</id> <name> <first id=”#name.first”>Mårten</first> <last id=”#name.last”>Gustafson</last> </name> </user> //last[1] * Still works
75. <user> <id>1234</id> <name> <first id=”#name.first”>Mårten</first> <last id=”#name.last”>Gustafson</last> </name> </user> //*[@id='#name.last'][1] * Adaptive
76. <user> <id>1234</id> <first id=”#name.first”>Mårten</first> <last id=”#name.last”>Gustafson</last> </user> //*[@id='#name.last'][1] * Still works
77. <named> <first id="#name.first">Mårten</first> <last id="#name.last">Gustafson</last> </named> //*[@id='#name.last'][1] * Still works
78. <yeah> <foo id="#name.first">Mårten</foo> <bar id="#name.last">Gustafson</bar> </yeah> //*[@id='#name.last'][1] * Still works
79. INFORMATION MODELLING * This is hard, usually “versioning hard”
80. #name.first * Format * Values * Guarantees
81. URL DNS MIME LINKS PROXY
82. URL DNS MIME LINKS =CONTRACT
83. ?
84. @martengustafson marten.gustafson@gmail.com http://marten.gustafson.pp.se/talks * Representations