REST - Valtech

Presentation on REST given at Valtech Stockholm.

Approx 60 minutes.

Transcript

1. Hi!
   My name is Mårten Gustafson
   

   View Slide

2. I used to work here...
   

   View Slide

3. ...now I work here...
   (and I brought give-away readers)
   

   View Slide

4. Representational State Transfer
   

   View Slide

5. Representational State Transfer
   

   View Slide

6. REST
   

   View Slide

7. RESTful
   

   View Slide

8. HTTP
   

   View Slide

9. means of
   INTEGRATING
   disparate stuff
   

   View Slide

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
    

    View Slide

11. INTEGRATIONs
    

    View Slide

12. APIs
    

    View Slide

13. INTERFACEs
    

    View Slide

14. UNIFORM
    * REST defines a uniform interface
    * As opposed to SOAP, CORBA, etc
    

    View Slide

15. GET
    PUT
    POST
    DELETE
    - list all foo
    - 501
    - create a new foo
    - 501
    a/b/c/foo
    

    View Slide

16. GET
    PUT
    POST
    DELETE
    - details of {id}
    - update the {id}
    - 501
    - delete the {id}
    a/b/c/foo/{id}
    

    View Slide

17. VERBs
    

    View Slide

18. (OPTIONS)
    * not common (yet)
    * mention: pre-flight
    

    View Slide

19. GET
    * retrieve
    

    View Slide

20. HEAD
    * retrieve without content (ie metadata)
    

    View Slide

21. POST
    * create (without known id) or update (with/without - unsafe)
    

    View Slide

22. PUT
    * update or create with known id (idempotent)
    

    View Slide

23. DELETE
    * remove
    

    View Slide

24. (TRACE)
    * ?
    

    View Slide

25. (CONNECT)
    * ?
    

    View Slide

26. IDEMPOTENT
    * Without side effects
    * Fine to call multiple times
    

    View Slide

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
    

    View Slide

28. DEVELOPing
    

    View Slide

29. WELL BEHAVED
    * be well behaved
    * read up on HTTP/1.1
    

    View Slide

30. ETag
    * The most overlooked HTTP header in API design?
    Allows concurrency control
    * if-match: “”
    * if-none-match: “”
    * 304 not modified
    * version number
    

    View Slide

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)
    

    View Slide

32. CACHE-CONTROL
    * age
    * no-cache
    * no-store
    

    View Slide

33. EXPIRES
    * Expire any cached copies after...
    

    View Slide

34. BENEFITs
    

    View Slide

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)
    

    View Slide

36. PLANNING
    

    View Slide

37. URLs
    * What will your URL scheme look like
    * How will it evolve
    * Identify natural points of extension/evolution
    

    View Slide

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?
    

    View Slide

39. SECURITY
    * HTTPS + basic auth (one stop shop)
    * API auth (client certificates, OAuth)
    * SSL cookies
    

    View Slide

40. VERSIONING
    * This is the hard part
    

    View Slide

41. http://api.foo/v1/bar
    application/xml
    + easy (ie browser compatible)
    

    View Slide

42. http://api.foo/v1/bar
    application/xml
    - URL changes with version
    - Breaks the URL = resource REST thingy
    

    View Slide

43. http://api.foo/bar
    application/vnd.bar-v1+xml
    - hard (ie NOT browser compatible)
    

    View Slide

44. http://api.foo/bar
    application/vnd.bar-v1+xml
    + version is independent of URL
    

    View Slide

45. application/vnd.foo-v1+xml
    application/vnd.foo-v2+xml
    * Vary: “Accept”
    

    View Slide

46. REPRESENTATION
    

    View Slide

47. http://api.foo/bar
    application/xml
    + easy (ie browser compatible)
    

    View Slide

48. http://api.foo/bar.xml
    + even easier (ie really browser compatible)
    - more info in URL
    

    View Slide

49. http://api.foo/bar
    application/vnd.bar-v1+xml
    

    View Slide

50. http://api.foo/bar
    application/vnd.bar-v1+xml
    + representation is independent of URL
    

    View Slide

51. USABILITY
    

    View Slide

52. PROXIES
    

    View Slide

53. http://api.foo/v1/bar.xml
    

    View Slide

54. http://api.foo/v1/bar.xml
    

    View Slide

55. http://api.foo/v1/bar.xml
    http://api.foo/bar
    

    View Slide

56. http://api.foo/v1/bar.xml
    http://api.foo/bar
    application/vnd.bar-v1+xml
    

    View Slide

57. http://api.foo/v1/bar.xml
    http://api.foo/bar
    application/vnd.bar-v1+xml
    

    View Slide

58. http://api.foo/v1/bar.xml
    http://api.foo/bar
    application/vnd.bar-v1+xml
    

    View Slide

59. HATEOAS
    

    View Slide

60. WAT?!
    

    View Slide

61. LINKs
    * State transitions
    

    View Slide

62. MIMEs
    * Representations
    

    View Slide

63. LINK + MIME
    

    View Slide

64. CONTRACTS
    * What do we promise our clients?
    * Read these:
    - http://martinfowler.com/bliki/TolerantReader.html
    - http://martinfowler.com/articles/consumerDrivenContracts.html
    

    View Slide

65. SERIALIZED
    FORM
    + Easy programming (initially, typed proxies)
    - Rigid (will not bend, will break)
    

    View Slide

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)
    

    View Slide

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
    

    View Slide

68. ROBUSTNESS
    

    View Slide

69. 
    1234
    
    Mårten
    Gustafson
    
    
    * XPath
    

    View Slide

70. 
    1234
    
    Mårten
    Gustafson
    
    
    /user/name/last
    * Rigid
    

    View Slide

71. 
    1234
    
    Mårten
    Gustafson
    
    
    //last
    * Adaptive
    * Might return multiple
    

    View Slide

72. 
    1234
    
    Mårten
    Gustafson
    
    
    //last[1]
    * Adaptive
    * Only one
    

    View Slide

73. 
    1234
    
    Mårten
    Gustafson
    
    
    * Annotated
    

    View Slide

74. 
    1234
    
    Mårten
    Gustafson
    
    
    //last[1]
    * Still works
    

    View Slide

75. 
    1234
    
    Mårten
    Gustafson
    
    
    //*[@id='#name.last'][1]
    * Adaptive
    

    View Slide

76. 
    1234
    Mårten
    Gustafson
    
    //*[@id='#name.last'][1]
    * Still works
    

    View Slide

77. 
    Mårten
    Gustafson
    
    //*[@id='#name.last'][1]
    * Still works
    

    View Slide

78. 
    Mårten
    Gustafson
    
    //*[@id='#name.last'][1]
    * Still works
    

    View Slide

79. INFORMATION
    MODELLING
    * This is hard, usually “versioning hard”
    

    View Slide

80. #name.first
    * Format
    * Values
    * Guarantees
    

    View Slide

81. URL
    DNS
    MIME
    LINKS
    PROXY
    

    View Slide

82. URL
    DNS
    MIME
    LINKS
    =CONTRACT
    

    View Slide

83. ?
    

    View Slide

84. @martengustafson
    marten.gustafson@gmail.com
    http://marten.gustafson.pp.se/talks
    * Representations
    

    View Slide