REST - Valtech

REST - Valtech

Presentation on REST given at Valtech Stockholm.

Approx 60 minutes.

A204e1fe2002bc6d087391759c3dfab0?s=128

Mårten Gustafson

March 09, 2012
Tweet

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