Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Designing Practical RESTful APIs

145 views

Published on

Slides at @trbmeetup
https://trbmeetup.doorkeeper.jp/events/73198

Published in: Software
  • Be the first to comment

  • Be the first to like this

Designing Practical RESTful APIs

  1. 1. Designing Practical RESTful APIs
  2. 2. Who am I? • Hiroshi Ogino • web developer • home-based worker • founder of @yurufuwarb
  3. 3. Agenda • What is REST? • How should we design practical APIs? • Conclusion
  4. 4. Agenda • What is REST? • How should we design practical APIs? • Conclusion
  5. 5. REST • REpresentational State Transfer • Architecture style, where data and functionality are accessed as URIs • Simple, Lightweight, and Fast
  6. 6. 3 Essential points
  7. 7. REST • Resource-Oriented • Uniform Interface • Stateless
  8. 8. Resource-Oriented • Addressable, Indexable • Resources are identified as Uniform Resource Identifiers (URIs) • Connectedness • Resources should link together in their representation
  9. 9. The world is filled with a lot of resources
  10. 10. https://xxx/truck https://yyy/car They are Identified by URI https://zzz/windmill
  11. 11. REST • Resource-Oriented • Uniform Interface • Stateless
  12. 12. HTTP METHODS Uniform Resource Locator (URL) GET PUT PATCH POST DELETE Collection https://api.xxx/items List details of the collection Replace the entire collection with another one Not generally used Create a new entry in the collection Delete a entire collection Element https://api.xxx/items/12 Retrieve a representation of the member of the collection Replace the member of the collection, or Create it if it does not exist Update the member of the collection Not generally used Delete the member of the collection
  13. 13. REST • Resource-Oriented • Uniform Interface • Stateless
  14. 14. Hi, for here or to go? For here. STATEFUL
  15. 15. What can I get you? Can I have two cheeseburgers and one order of fries? STATEFUL
  16. 16. What size fries would you like? Small. STATEFUL
  17. 17. Would you like anything to drink? I’ll have coke. STATEFUL
  18. 18. Would you like anything else? No, I’m good. STATEFUL
  19. 19. STATEFUL • Cashier remembers your past orders • You only have to put your latest order
  20. 20. Hi, for here or to go? For here. STATELESS
  21. 21. What can I get you? For here. Can I have two cheeseburgers and one order of fries? STATELESS
  22. 22. What size fries would you like? For here. Can I have two cheeseburgers and one order of fries? Small. STATELESS
  23. 23. Would you like anything to drink? For here. Can I have two cheeseburgers and one order of fries? Small. I’ll have coke. STATELESS
  24. 24. STATELESS • Cashier DOES NOT remember your past orders • You have to put orders including past orders
  25. 25. STATELESS • Cashier DOES NOT remember your past orders • You have to put orders including past orders What good will come of it? 🤔
  26. 26. STATELESS • It was said that the main advantage of STATELESS was SCALABILITY in the past • It was believed that STATEFUL COULD NOT scale out
  27. 27. STATELESS • It was said that the main advantage of STATELESS was SCALABILITY in the past • It was believed that STATEFUL COULD NOT scale out • Nowadays … • LB can dispatch the same server which is scaled out • scaled out servers can share the same session store (RDS, Redis, …) It’s no longer a big deal!
  28. 28. Agenda • What is REST? • How should we design practical APIs? • Conclusion
  29. 29. PRACTICAL … ?
  30. 30. Practical • Dictionary says • involving activity rather than study or theory • likely to be successful or useful
  31. 31. Practical SHU-HA-RI is a Japanese martial art concept, and describes the stage of learning to mastery
  32. 32. Practical Repeat the forms and discipline ourselves to absorb the forms and to find the values lurking behind them SHU → obey, protect
  33. 33. Practical Based on the fundamentals learned with break the forms and make innovation HA → detach ,
  34. 34. Practical Completely depart from the forms, act in accordance with what we want RI → leave
  35. 35. Practical Find the key to PRACTICAL hiding around here
  36. 36. Practical • Dictionary says • involving activity rather than study or theory • likely to be successful or useful • MAY NOT OBEY all constraints of the REST architecture style • BREAK theory now and then for a specific purpose • FOCUS ON successful / useful
  37. 37. 3 Questions Reaching Practical Design
  38. 38. Q.1 How should we design the ENDPOINT to get our own information?
  39. 39. GET /customers/:id From GET method, easy to expect retrieving the customer information from customers table while requesting Anyone CAN GUESS other’s endpoints
  40. 40. GET /me or /mypage From GET method, easy to expect retrieving my information from customers table while requesting Anyone CAN NOT GUESS other’s endpoints
  41. 41. However, we need to store customer_id in a session to identify the customer and it makes this endpoint STATEFUL … is it okay? 🤔 GET /me or /mypage
  42. 42. STATELESS • It was said that the main advantage of STATELESS was SCALABILITY in the past • It was believed that STATEFUL COULD NOT scale out • Nowadays … • LB can dispatch the same server which is scaled out • scaled out servers can share the same session store (RDS, Redis, …) It’s no longer a big deal!
  43. 43. REMAINS scalable even if we store customer_id in a session Caution: we should not manage long-life objects in a session because it may deprive the independency of each request GET /me or /mypage
  44. 44. Learned from Q.1 • SHOULD NOT allow anyone to guess the other’s endpoints if the resources of the endpoint are serious information • CAN use a session for a specific purpose
  45. 45. Q.2 How should we design the RESOURCE and the ENDPOINT that allow customers to agree with the Terms of Service?
  46. 46. Q.2 How should we design the RESOURCE and the ENDPOINT that allow customers to agree with the Terms of Service?
  47. 47. This resource CAN NOT represent updating Terms of Service This resource CAN NOT manage enforced datetime id int nickname string : agreement booleancustomers ADD agreement column to customers table
  48. 48. This resource CAN represent updating Terms of Service This resource CAN manage enforced datetime ● enforced date is managed by version column ● enforced datetime is managed by start_at column CREATE terms / terms_agreement tables customers term_agreements terms id int version string start_at datetime : id int customer_id int term_id int :
  49. 49. Q.2 How should we design the RESOURCE and the ENDPOINT that allow customers to agree with the Terms of Service?
  50. 50. :version is enforced date (ex. /terms/20180515/agreements) clear to agree with which version of terms From POST method, easy to expect inserting a new term agreement record while requesting POST /terms/:version/agreements
  51. 51. Learned from Q.2 • SHOULD maximize representation of a resource • SHOULD make an Endpoint semantic
  52. 52. Q.3 How should we design the SEQUENCE in which customers buy something in an application?
  53. 53. Back-end ServerCustomer https://api.example.com/items Network (1) SEARCH Back-end ServerCustomer Network (2) CONFIRM Back-end ServerCustomer Network (3) PURCHASE https://api.example.com/items/order? confirm=true https://api.example.com/items/order
  54. 54. Customer STORE purchase data CONFIRM Network Back-end Server Session Store COMPLETE confirmation PURCHASE VALIDATE purchase data DELETE purchase data PROCESS purchase COMPLETE purchase - (2) CONFIRM - (3) PURCHASE
  55. 55. Customer STORE purchase data CONFIRM Network Back-end Server Session Store PURCHASE VALIDATE purchase data DELETE purchase data PROCESS purchase - PREVENT duplicated requests COMPLETE confirmation COMPLETE purchase
  56. 56. Learned from Q.3 • SHOULD establish a confirmation phase to operate significant action, such as a purchase • MUST use a session intentionally to prevent duplicated requests
  57. 57. Agenda • What is REST? • How should we design practical APIs? • Conclusion
  58. 58. Learned from Q.1 • SHOULD NOT allow anyone to guess the other’s endpoints if the resources of the endpoint are serious information • CAN use a session for a specific purpose
  59. 59. Learned from Q.2 • SHOULD maximize representation of a resource • SHOULD make an Endpoint semantic
  60. 60. Learned from Q.3 • SHOULD establish a confirmation phase to operate significant action, such as a purchase • MUST use a session intentionally to prevent duplicated requests
  61. 61. Thank you

×