REST - Valtech

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