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
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
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
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