REST API edge cases

If you're lucky you can use so-called REST APIs in your daily work. Except, some of the largest (social) APIs make mistakes against the basic rules of REST. If you happen to be in the process of designing a REST API, you better refresh your knowledge on those REST principles. This talk will explain some quick REST API principles with lots of real-life examples, followed by some edge case designs including soft-deletes and "likes" as sub resources.

Presented at Laravel Brussels meetup in Antwerp.

Transcript

1. REST API edge cases
   Soft-deletes, likes/stars/tags
   

   View Slide

2. Hi, my name is Hannes.
   

   View Slide

3. laravel
   

   View Slide

4. mongodb
   

   View Slide

5. couchdb
   

   View Slide

6. madewithlove
   

   View Slide

7. • Developer
   • Laravel since 4.0.0-BETA2
   • madewithlove
   ABOUT ME
   

   View Slide

8. REST API
   

   View Slide

9. A Github user stars a repository
   

   View Slide

10. STAR /repos/username/repo…
    

    View Slide

11. A user archives an email
    

    View Slide

12. ARCHIVE /emails/159803922
    

    View Slide

13. UNARCHIVE /emails/159803922
    

    View Slide

14. • REST basics
    • Case study
    • How it’s done
    REST API FOR LIKES
    

    View Slide

15. 1. REST basics
    

    View Slide

16. View Slide

17. REST BASICS - SOAP
    POST /SomeService.aspx
    Host: example.org
    

    View Slide

18. REST BASICS - SOAP
    
    xmlns:soap="http://www.w3.org/2001/…"
    soap:encodingStyle="http://www.w3.org/2001/…">
    
    
    IBM
    
    
    
    

    View Slide

19. REST BASICS - REST EQUIVALENT
    GET /stocks/ibm HTTP/1.1
    Host: example.org
    Accept: application/xml
    

    View Slide

20. CRUD - HTTP verbs
    

    View Slide

21. REST BASICS - HTTP METHOD - CREATE
    Create: POST
    

    View Slide

22. REST BASICS - HTTP METHODS - CREATE
    POST /notes HTTP/1.1
    Host: example.org
    

    View Slide

23. REST BASICS - HTTP METHODS - CREATE
    Create: POST or PUT
    

    View Slide

24. REST BASICS - HTTP METHODS - CREATE
    PUT /notes/meeting1-report HTTP/1.1
    Host: example.org
    

    View Slide

25. REST BASICS - HTTP METHODS - READ
    Read: GET
    

    View Slide

26. REST BASICS - HTTP METHODS - READ
    GET /users/driesvints HTTP/1.1
    Host: api.github.com
    HTTP/1.1 200 OK
    

    View Slide

27. REST BASICS - HTTP METHODS - UPDATE
    Update: PUT
    

    View Slide

28. REST BASICS - HTTP METHODS - UPDATE
    PUT /users/driesvints HTTP/1.1
    Host: api.github.com
    {
    "login": "driesvints",
    "id": 594614,
    "avatar_url": "https://avatars.gith…",
    "email": "dries@beatswitch.com",
    …
    

    View Slide

29. REST BASICS - HTTP METHODS - UPDATE
    Update: PUT or PATCH
    

    View Slide

30. REST BASICS - HTTP METHODS - UPDATE
    PATCH /users/driesvints HTTP/1.1
    Host: api.github.com
    email=dries@beatswitch.com
    

    View Slide

31. REST BASICS - HTTP METHODS - DELETE
    Delete: DELETE
    

    View Slide

32. REST BASICS - HTTP METHODS - DELETE
    DELETE /repos/driesvints/docs HTTP/1.1
    Host: api.github.com
    HTTP/1.1 204 No Content
    

    View Slide

33. Headers
    

    View Slide

34. /followers/ids.json
    REST BASICS - HTTP HEADERS - CONTENT TYPE
    

    View Slide

35. REST BASICS - HTTP HEADERS - CONTENT TYPE
    Accept:
    application/json
    

    View Slide

36. https://api.twitter.com/1.0/
    https://api.twitter.com/1.1/
    REST BASICS - HTTP HEADERS - VERSION
    

    View Slide

37. Accept:
    application/vnd.github.v3+json
    REST BASICS - HTTP HEADERS - VERSION
    

    View Slide

38. REST BASICS - HTTP HEADERS - AUTHENTICATION
    https://api.instagram.com/v1/users/
    self?access_token=r4nd0m0123456789
    

    View Slide

39. GET /users/driesvints HTTP/1.1
    Host: api.github.com
    Authorization: Bearer r4nd0m0123456789
    REST BASICS - HTTP HEADERS - AUTHENTICATION
    

    View Slide

40. REST BASICS - HTTP HEADERS - RATE LIMIT
    https://api.twitter.com/1.1/
    application/rate_limit_status.json
    

    View Slide

41. REST BASICS - HTTP HEADERS - RATE LIMIT - GH
    HTTP/1.1 403 Forbidden
    X-RateLimit-Limit: 60
    X-RateLimit-Remaining: 0
    X-RateLimit-Reset: 1377013266
    

    View Slide

42. REST BASICS - HTTP HEADERS - RATE LIMIT
    HTTP/1.1 429 Too Many Requests
    X-RateLimit-Limit: 60
    X-RateLimit-Remaining: 0
    X-RateLimit-Reset: 1377013266
    

    View Slide

43. HTTP/1.1 429 Too Many Requests
    X-RateLimit-UserLimit: 60
    X-RateLimit-UserRemaining: 0
    X-RateLimit-UserReset: 1377…
    REST BASICS - HTTP HEADERS - RATE LIMIT
    

    View Slide

44. HTTP/1.1 429 Too Many Requests
    X-RateLimit-ClientLimit: 60
    X-RateLimit-ClientRemaining: 0
    X-RateLimit-ClientReset: 1377…
    REST BASICS - HTTP HEADERS - RATE LIMIT
    

    View Slide

45. URL scheme
    

    View Slide

46. REST BASICS - URL SCHEME
    Required params = URL segments
    

    View Slide

47. REST BASICS - URL SCHEME
    Optional params = GET params
    

    View Slide

48. REST BASICS - URL SCHEME
    /orgs/{org_slug}/report/
    {start_date}/{end_date}
    

    View Slide

49. REST BASICS - URL SCHEME
    /orgs/mwl/report/
    2014-01-01/2014-06-30
    

    View Slide

50. REST BASICS - URL SCHEME
    /orgs/mwl/report
    ?start_date=2014-01-01
    &end_date=2014-06-30
    

    View Slide

51. REST BASICS - RECAP
    • HTTP Verbs
    • HTTP Headers
    • Required vs. Optional
    

    View Slide

52. 2. Case study
    

    View Slide

53. CASE STUDY - TWITTER
    Twitter favorites
    

    View Slide

54. CASE STUDY - TWITTER - FAVORITED?
    GET /1.1/statuses/show/51673… HTTP/1.1
    Host: api.twitter.com
    {
    "favorited": true,
    …
    

    View Slide

55. CASE STUDY - TWITTER - FAVORITE
    POST /1.1/favorites/create.json?id=51673… HTTP/1.1
    Host: api.twitter.com
    

    View Slide

56. CASE STUDY - TWITTER - UNFAVORITE
    POST /1.1/favorites/destroy.json?id=51673… HTTP/1.1
    Host: api.twitter.com
    

    View Slide

57. CASE STUDY - GITHUB
    Github stargazers
    

    View Slide

58. CASE STUDY - GITHUB - STARRED?
    GET /user/starred/:owner/:repo HTTP/1.1
    Host: api.github.com
    HTTP/1.1 204 No Content
    HTTP/1.1 404 Not found
    

    View Slide

59. CASE STUDY - GITHUB - STAR
    PUT /user/starred/:owner/:repo HTTP/1.1
    Host: api.github.com
    HTTP/1.1 204 No Content
    

    View Slide

60. CASE STUDY - GITHUB - UNSTAR
    DELETE /user/starred/:owner/:repo HTTP/1.1
    Host: api.github.com
    HTTP/1.1 204 No Content
    

    View Slide

61. CASE STUDY - FOURSQUARE
    Foursquare likes
    

    View Slide

62. CASE STUDY - FOURSQUARE - LIKED?
    GET /v2/venues/4b292… HTTP/1.1
    Host: api.foursquare.com
    {
    "like": true,
    …
    

    View Slide

63. CASE STUDY - FOURSQUARE - LIKED?
    GET /v2/venues/4b292… HTTP/1.1
    Host: api.foursquare.com
    {
    "dislike": true,
    …
    

    View Slide

64. CASE STUDY - FOURSQUARE - LIKE
    POST /v2/venues/4b292…/like HTTP/1.1
    Host: api.foursquare.com
    set=1
    

    View Slide

65. CASE STUDY - FOURSQUARE - UNLIKE
    POST /v2/venues/4b292…/like HTTP/1.1
    Host: api.foursquare.com
    set=0
    

    View Slide

66. CASE STUDY - FOURSQUARE - LIKE
    POST /v2/checkins/4b292…/like HTTP/1.1
    Host: api.foursquare.com
    set=1
    

    View Slide

67. CASE STUDY - FOURSQUARE - UNLIKE
    POST /v2/checkins/4b292…/like HTTP/1.1
    Host: api.foursquare.com
    set=0
    

    View Slide

68. CASE STUDY - INSTAGRAM
    Instagram likes
    

    View Slide

69. CASE STUDY - INSTAGRAM - LIKED?
    GET /v1/media/4b292…/likes HTTP/1.1
    Host: api.instagram.com
    {
    "data": [
    {
    "username": "gilbert_west",
    "id": "586708382",
    …
    

    View Slide

70. CASE STUDY - INSTAGRAM - LIKE
    POST /v1/media/4b292…/likes HTTP/1.1
    Host: api.instagram.com
    

    View Slide

71. CASE STUDY - INSTAGRAM - UNLIKE
    DELETE /v1/media/4b292…/likes HTTP/1.1
    Host: api.instagram.com
    

    View Slide

72. 3. How it’s done
    

    View Slide

73. In my opinion
    

    View Slide

74. Github + Instagram
    HOW IT’S DONE - LIKES
    

    View Slide

75. HOW IT’S DONE - LIKES - LIKED?
    GET /notes/{id} HTTP/1.1
    Host: example.org
    {
    "liked": true,
    …
    

    View Slide

76. HOW IT’S DONE - LIKES - PEOPLE WHO LIKED
    GET /notes/{id}/likes HTTP/1.1
    Host: example.org
    

    View Slide

77. HOW IT’S DONE - LIKES - LIKE
    PATCH /notes/{id} HTTP/1.1
    Host: example.org
    liked=true
    

    View Slide

78. HOW IT’S DONE - LIKES - UNLIKE
    PATCH /notes/{id} HTTP/1.1
    Host: example.org
    liked=false
    

    View Slide

79. Soft delete?
    DELETE /endpoint
    

    View Slide

80. HOW IT’S DONE - SOFT DELETE
    DELETE /notes/1234 HTTP/1.1
    Host: example.org
    

    View Slide

81. HOW IT’S DONE - SOFT DELETE
    GET /deleted_notes HTTP/1.1
    Host: example.org
    

    View Slide

82. HOW IT’S DONE - SOFT DELETE
    PATCH /deleted_notes/1234 HTTP/1.1
    Host: example.org
    deleted=false
    

    View Slide

83. Archiving?
    

    View Slide

84. HOW IT’S DONE - ARCHIVING
    PATCH /notes/1234 HTTP/1.1
    Host: example.org
    archived=true
    

    View Slide

85. HOW IT’S DONE - ARCHIVING
    GET /archived_notes HTTP/1.1
    Host: example.org
    

    View Slide

86. HOW IT’S DONE - ARCHIVING
    PATCH /archived_notes/1234 HTTP/1.1
    Host: example.org
    archived=false
    

    View Slide

87. • Likes
    • Soft deletes
    • Archiving
    RECAP - EDGE CASES
    

    View Slide

88. • REST basics
    • Case study
    • How it’s done
    RECAP
    

    View Slide

89. View Slide

90. View Slide

91. Questions/discussions
    

    View Slide

92. Thank you!
    @hannesvdvreken
    

    View Slide

93. • http:/
    /wikipedia.org/wiki/SOAP
    • http:/
    /meetup.com/mongodb-belgium
    • http:/
    /mwl.be
    • http:/
    /shop.oreilly.com/product/0636920028468.do
    • https:/
    /leanpub.com/build-apis-you-wont-hate
    • https:/
    /dev.twitter.com
    • http:/
    /instagram.com/developer
    • https:/
    /developer.github.com
    • https:/
    /developer.foursquare.com
    REFERENCES
    

    View Slide