10 things you are doing wrong with REST

Transcript

1. 10 things you are doing
   wrong with REST
   1
   PFCongres - Utrecht
   13-14 september
   *
   * almost
   

   View Slide

2. Joshua Thijssen
   Freelance consultant and trainer @
   NoxLogic & TechAdemy
   Founder of the Dutch Web Alliance.
   Development in PHP, Python, Perl, C,
   Java. Lead developer of Saffire.
   Blog: http://adayinthelifeof.nl
   Email: jthijssen@noxlogic.nl
   Twitter: @jaytaph
   

   View Slide

3. http://www.phparch.com/books/mastering-the-spl-library/
   PDF, ePub, Mobi, or hardcopy
   

   View Slide

4. View Slide

5. View Slide

6. View Slide

7. View Slide

8. View Slide

9. View Slide

10. View Slide

11. View Slide

12. View Slide

13. View Slide

14. View Slide

15. View Slide

16. View Slide

17. View Slide

18. View Slide

19. View Slide

20. View Slide

21. WORLD WIDE WEB
    powered by
    HTTP 0.9
    21
    

    View Slide

22. HTTP 1.0 (rfc 1945)
    T. Berners-Lee
    Roy T. Fielding
    H. Frystyk
    22
    

    View Slide

23. 23
    “This is how we do webby things from now on”
    

    View Slide

24. Roy T. Fielding
    24
    (the T stands for kickass)
    

    View Slide

25. 25
    I want to get a Ph.D in webby stuff!
    Write a dissertation!
    Here it is!
    Pass
    Roy T. Fielding wrote a dissertation:
    

    View Slide

26. 26
    chapter 5
    (rest)
    Architectural Styles and the
    Design of Network-based
    Software Architectures
    

    View Slide

27. 27
    ➡ client-server
    ➡ stateless
    ➡ cacheable
    ➡ layered system
    ➡ code-on-demand (optional constraint)
    ➡ uniform interface
    

    View Slide

28. 28
    What’s the hype about REST?
    

    View Slide

29. ➡ REST will not make things automatically
    easier for you.
    ➡ REST is not black magic that solves all your
    problems.
    ➡ REST does not mean your API will scale to
    facebook/twitter sizes.
    ➡ REST is not even a protocol.
    29
    

    View Slide

30. ➡ REST is a combination of several
    architectural styles.
    ➡ (LCSS$ + uniform interface)
    30
    

    View Slide

31. 31
    ➡ identification of resources
    ➡ manipulation of resources through
    representations
    ➡ self-descriptive messages
    ➡ hypermedia as the engine of application
    state
    URIs
    HTTP requests & responses
    HTTP headers & mime types
    Links inside media types
    

    View Slide

32. ➡ (network) visibility
    ➡ simplicity
    ➡ better user experience
    ➡ scalability
    ➡ evolvability
    32
    

    View Slide

33. ➡ REST is (transport) protocol agnostic
    33
    

    View Slide

34. ➡ GET /article/1234
    ➡ PUT /article/1234
    ➡ POST /articles
    ➡ DELETE /article/1234
    34
    

    View Slide

35. ➡ RETR /article/1234
    ➡ STOR /article/1234
    ➡ STOR /articles
    ➡ DELE /article/1234
    35
    

    View Slide

36. ➡ REST provide you the means to create a
    scalable / evolvable API.
    ➡ That doesn’t automatically make it happen.
    ➡ If you API is crap, REST won’t help.
    36
    

    View Slide

37. 37
    HTTP APIs. ARE. COOL.
    

    View Slide

38. 38
    PUT vs POST
    

    View Slide

39. 39
    ➡ Isn’t a (true) REST problem
    ➡ HTTP problem
    

    View Slide

40. 40
    PUT or POST?
    PUT when the resource URI is known
    POST when it’s not (server decides location)
    PUT /user/jthijssen/talk/123
    POST /user/jthijssen/talks
    

    View Slide

41. 41
    PUT /user/jthijssen/talk/123
    POST /user/jthijssen/talks
    PUT = idempotent, POST is not!
    PUT /user/jthijssen/talk/123
    PUT /user/jthijssen/talk/123
    POST /user/jthijssen/talks
    POST /user/jthijssen/talks
    POST is the worst option for caching / scalability,
    but use it if you don’t know what to do.
    

    View Slide

42. No hypermedia /
    HATEOAS
    42
    

    View Slide

43. hypermedia format?
    43
    

    View Slide

44. 44
    text
    Once upon a midnight dreary, while I pondered weak and weary,
    Over many a quaint and curious volume of forgotten lore,
    While I nodded, nearly napping, suddenly there came a tapping,
    As of some one gently rapping, rapping at my chamber door.
    `'Tis some visitor,' I muttered, `tapping at my chamber door -
    Only this, and nothing more.'
    just data
    

    View Slide

45. 45
    hypertext
    Once upon a midnight dreary, while I pondered weak and
    weary, Over many a quaint and curious volume of forgotten lore,
    While I nodded, nearly napping, suddenly there came a tapping,
    As of some one gently rapping, rapping at my chamber door. `'Tis
    some visitor,' I muttered, `tapping at my chamber door -
    Only this, and nothing more.'
    links point to other textual data
    

    View Slide

46. 46
    hypermedia
    
    
    Once upon a midnight dreary, while I pondered weak and
    weary, Over many a quaint and curious volume of forgotten lore,
    While I nodded, nearly napping, suddenly there came a tapping,
    As of some one gently rapping, rapping at my chamber door. `'Tis
    some visitor,' I muttered, `tapping at my chamber door -
    Only this, and nothing more.'
    
    
    
    
    
    
    
    
    links to different types of (hyper)media
    (hypertext + multimedia)
    

    View Slide

47. 47
    ➡ HTML, JSON, XML, TEXT.
    ➡ Not hypermedia.
    

    View Slide

48. 48
    ➡ XHTML
    ➡ Collection+JSON
    ➡ HAL
    ➡ Siren
    ➡ Custom type (application/vnd.*+format)
    

    View Slide

49. 49
    ➡ My hovercraft is full of eels.
    ➡
    

    View Slide

50. 50
    ➡ Hypertext as the engine of application state
    ➡ Hypermedia format with not only data, but
    also specifies operations on that data
    ➡ (Finite) state machine
    

    View Slide

51. 51
    pfz airlines
    

    View Slide

52. 52
    ➡ search tickets
    ➡ confirm ticket, select seats etc
    ➡ pay your ticket
    ➡ get e-ticket
    

    View Slide

53. 53
    POST /search?order=price&limit=5 HTTP/1.1
    Host: api.pfz-airlines.com
    Accept: application/vnd.pfz.flights+xml ; version: 1.0
    
    LAS
    14-oct-2012
    21-oct-2012
    firstclass
    
    

    View Slide

54. 54
    HTTP/1.1 200 OK
    Content-type: application/vnd.pfz.flights+xml ; version: 1.0
    
    
    
    
    
    
    
    
    
    
    

    View Slide

55. 55
    POST /confirm/flight/15263HTTP/1.1
    Host: api.pfz-airlines.com
    Accept: application/vnd.pfz.flights+xml ; version: 1.0
    
    2A
    vegetarian
    
    HTTP/1.1 401 Authentication required
    

    View Slide

56. 56
    POST /confirm/flight/15263HTTP/1.1
    Host: api.pfz-airlines.com
    Accept: application/vnd.pfz.booking+xml ; version: 1.0
    Authorization: OAuth ......
    
    2A
    vegetarian
    
    HTTP/1.1 201 Created
    Location: /booking/1616163
    
    1616163
    
    
    
    
    

    View Slide

57. 57
    OPTIONS /booking/1616163 HTTP/1.1
    Host: api.pfz-airlines.com
    Authorization: OAuth ......
    HTTP/1.1 200 OK
    Allow: GET, DELETE, PUT
    

    View Slide

58. 58
    DELETE /booking/1616163 HTTP/1.1
    Host: api.pfz-airlines.com
    Authorization: OAuth ......
    HTTP/1.1 204 No content
    

    View Slide

59. 59
    GET /booking/1616163 HTTP/1.1
    Host: api.pfz-airlines.com
    Accept: application/vnd.pfz.booking+xml ; version: 1.0
    Authorization: OAuth...
    HTTP/1.1 200 OK
    
    
    PF123
    14:24
    
    
    
    2A
    vegetarian
    
    Movie that you already saw
    Another movie you don’t care about
    And a chickflic movie, so you don’t want to watch
    Episode of Friends
    Episode of Friends
    Episode of Friends
    Episode of Friends
    
    
    
    
    Not paid
    
    
    
    
    

    View Slide

60. 60
    PUT /payment/booking/1616163 HTTP/1.1
    Host: api.pfz-airlines.com
    Accept: application/vnd.pfz.payment+xml ; version: 1.0
    Authorization: OAuth ......
    
    4111-1111-1111-1111
    04/16
    Joshua Thijssen
    514.00
    
    HTTP/1.1 201 Created
    Location: /payment/booking/1616163
    

    View Slide

61. 61
    OPTIONS /booking/1616163 HTTP/1.1
    Host: api.pfz-airlines.com
    Authorization: OAuth ......
    HTTP/1.1 200 OK
    Allow: GET
    

    View Slide

62. 62
    GET /booking/1616163 HTTP/1.1
    Host: api.pfz-airlines.com
    Accept: application/vnd.pfz.booking+xml ; version: 1.0
    Authorization: OAuth...
    HTTP/1.1 200 OK
    
    
    PF123
    14:24
    
    
    
    2A
    vegetarian
    
    Movie that you already saw
    Another movie you don’t care about
    And a chickflic movie, so you don’t want to watch
    Episode of Friends
    Episode of Friends
    Episode of Friends
    Episode of Friends
    
    
    
    
    Paid in full
    
    
    
    
    
    

    View Slide

63. URL construction
    63
    

    View Slide

64. 64
    ➡ Never *EVER* construct URLs directly
    from code.
    

    View Slide

65. View Slide

66. 66
    url = MAIN_URL + “/” + user_id + “/talks”;
    rc = HTTP.post(url, data);
    

    View Slide

67. and now the server
    changes the location of
    your talks...
    67
    

    View Slide

68. View Slide

69. 69
    url = data.link_rel(“talks”, user_id);
    rc = HTTP.post(url, data);
    Uri can change: server, uri, protocol, port etc..
    

    View Slide

70. implementation leaks
    70
    

    View Slide

71. 71
    ➡ It’s bad in code, it’s just as bad in API’s
    ➡ Leaking implementation means harder time
    to change your implementation
    ➡ Your implementation WILL change over
    time!
    

    View Slide

72. 72
    ➡ http://example.org/api.php/article/1234
    

    View Slide

73. 73
    GET /api/article/1234 HTTP/1.1
    Host: example.org
    Accept: application/json
    200 OK
    {
    "article" : {
    "id" : 1234,
    "name" : "red stapler",
    "price" : 24.99,
    "category" : "office supplies",
    "dt_created" : "2013-01-05 12:41:52",
    "dt_updated" : "2013-01-05 12:41:52"
    }
    }
    

    View Slide

74. ➡ You are not transmitting resources
    ➡ You are transmitting REPRESENTATIONS
    of resources
    74
    

    View Slide

75. GET /boats/pol-5831
    75
    

    View Slide

76. 76
    image/jpg
    

    View Slide

77. 77
    application/vnd.boat+xml
    
    
    white
    
    outboard
    115
    
    4
    
    

    View Slide

78. 78
    text/plain
    White boat with a johnson
    115HP outboard engine. There is
    room for 4 persons. It has been
    recently washed.
    

    View Slide

79. 79
    ➡ Don’t leak implementation.
    ➡ Use (custom) hypermedia formats so your
    implementation can change.
    ➡ Happy.
    

    View Slide

80. JSON only
    80
    

    View Slide

81. 81
    ➡ JSON is not a hypermedia format.
    ➡ JSON-HAL, JSON-LD, Collection+JSON
    are (but not standardized yet).
    ➡ A JSON-only API cannot be restful (as it
    does not use a hypermedia format)
    ➡ XML-only API is neither RESTful
    

    View Slide

82. 82
    {
    "article" : {
    "id" : 1234,
    "name" : "red stapler",
    "price" : 24.99,
    "category" : "office supplies",
    "dt_created" : "2013-01-05 12:41:52",
    "dt_updated" : "2013-01-05 12:41:52"
    }
    }
    

    View Slide

83. 83
    {
    "article" : {
    "id" : 1234,
    "name" : "red stapler",
    "price" : 24.99,
    "price_usd" : 29.99,
    "price_cad" : 31.99,
    "category" : "office supplies",
    "dt_created" : "2013-01-05 12:41:52",
    "dt_updated" : "2013-01-05 12:41:52"
    }
    }
    

    View Slide

84. 84
    
    red stapler
    
    24.99
    29.99
    31.99
    
    ...
    }
    

    View Slide

85. Every time you call
    your API “RESTful”, Roy
    Fielding will eat a cat*...
    85
    * probably not, but you get my point..
    

    View Slide