Upgrade to Pro — share decks privately, control downloads, hide ads and more …

REST API edge cases

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.

39eb3f3d313b13f05534e496285040b8?s=128

Hannes Van De Vreken

October 29, 2014
Tweet

Transcript

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

  2. Hi, my name is Hannes.

  3. laravel

  4. mongodb

  5. couchdb

  6. madewithlove

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

  8. REST API

  9. A Github user stars a repository

  10. STAR /repos/username/repo…

  11. A user archives an email

  12. ARCHIVE /emails/159803922

  13. UNARCHIVE /emails/159803922

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

    REST API FOR LIKES
  15. 1. REST basics

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

  18. REST BASICS - SOAP <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/…" soap:encodingStyle="http://www.w3.org/2001/…"> <soap:Body

    xmlns:m="http://www.example.org/stock"> <m:GetStockPrice> <m:StockName>IBM</m:StockName> </m:GetStockPrice> </soap:Body> </soap:Envelope>
  19. REST BASICS - REST EQUIVALENT GET /stocks/ibm HTTP/1.1 Host: example.org

    Accept: application/xml
  20. CRUD - HTTP verbs

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

  22. REST BASICS - HTTP METHODS - CREATE POST /notes HTTP/1.1

    Host: example.org
  23. REST BASICS - HTTP METHODS - CREATE Create: POST or

    PUT
  24. REST BASICS - HTTP METHODS - CREATE PUT /notes/meeting1-report HTTP/1.1

    Host: example.org
  25. REST BASICS - HTTP METHODS - READ Read: GET

  26. REST BASICS - HTTP METHODS - READ GET /users/driesvints HTTP/1.1

    Host: api.github.com HTTP/1.1 200 OK
  27. REST BASICS - HTTP METHODS - UPDATE Update: PUT

  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", …
  29. REST BASICS - HTTP METHODS - UPDATE Update: PUT or

    PATCH
  30. REST BASICS - HTTP METHODS - UPDATE PATCH /users/driesvints HTTP/1.1

    Host: api.github.com email=dries@beatswitch.com
  31. REST BASICS - HTTP METHODS - DELETE Delete: DELETE

  32. REST BASICS - HTTP METHODS - DELETE DELETE /repos/driesvints/docs HTTP/1.1

    Host: api.github.com HTTP/1.1 204 No Content
  33. Headers

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

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

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

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

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

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

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

  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
  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
  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
  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
  45. URL scheme

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

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

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

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

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

  51. REST BASICS - RECAP • HTTP Verbs • HTTP Headers

    • Required vs. Optional
  52. 2. Case study

  53. CASE STUDY - TWITTER Twitter favorites

  54. CASE STUDY - TWITTER - FAVORITED? GET /1.1/statuses/show/51673… HTTP/1.1 Host:

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

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

    api.twitter.com
  57. CASE STUDY - GITHUB Github stargazers

  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
  59. CASE STUDY - GITHUB - STAR PUT /user/starred/:owner/:repo HTTP/1.1 Host:

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

    api.github.com HTTP/1.1 204 No Content
  61. CASE STUDY - FOURSQUARE Foursquare likes

  62. CASE STUDY - FOURSQUARE - LIKED? GET /v2/venues/4b292… HTTP/1.1 Host:

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

    api.foursquare.com { "dislike": true, …
  64. CASE STUDY - FOURSQUARE - LIKE POST /v2/venues/4b292…/like HTTP/1.1 Host:

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

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

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

    api.foursquare.com set=0
  68. CASE STUDY - INSTAGRAM Instagram likes

  69. CASE STUDY - INSTAGRAM - LIKED? GET /v1/media/4b292…/likes HTTP/1.1 Host:

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

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

    api.instagram.com
  72. 3. How it’s done

  73. In my opinion

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

  75. HOW IT’S DONE - LIKES - LIKED? GET /notes/{id} HTTP/1.1

    Host: example.org { "liked": true, …
  76. HOW IT’S DONE - LIKES - PEOPLE WHO LIKED GET

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

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

    Host: example.org liked=false
  79. Soft delete? DELETE /endpoint

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

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

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

    example.org deleted=false
  83. Archiving?

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

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

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

    archived=false
  87. • Likes • Soft deletes • Archiving RECAP - EDGE

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

    RECAP
  89. None
  90. None
  91. Questions/discussions

  92. Thank you! @hannesvdvreken

  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