This document discusses designing practical RESTful APIs. It begins with an overview of REST principles including being resource-oriented, having a uniform interface, and being stateless. It then asks three questions about practical API design: 1) How to design an endpoint for a user to access their own information, concluding endpoints should not allow guessing others' resources and sessions can be used for specific purposes. 2) How to design agreeing to terms of service, concluding to maximize resource representation and make endpoints semantic. 3) How to design a purchase sequence, concluding to establish confirmation phases and intentionally use sessions to prevent duplicates. The document provides examples and discussions for each question to learn how to design practical yet useful APIs.

1. Designing
Practical
RESTful APIs

2. Who am I?
• Hiroshi Ogino
• web developer
• home-based worker
• founder of @yurufuwarb

3. Agenda
• What is REST?
• How should we design practical
APIs?
• Conclusion

4. Agenda
• What is REST?
• How should we design practical
APIs?
• Conclusion

5. REST
• REpresentational State Transfer
• Architecture style, where data and
functionality are accessed as URIs
• Simple, Lightweight, and Fast

6. 3 Essential points

7. REST
• Resource-Oriented
• Uniform Interface
• Stateless

8. Resource-Oriented
• Addressable, Indexable
• Resources are identified as Uniform
Resource Identifiers (URIs)
• Connectedness
• Resources should link together in
their representation

10. The world is filled
with a lot of resources

11. https://xxx/truck
https://yyy/car
They are Identified
by URI
https://zzz/windmill

12. REST
• Resource-Oriented
• Uniform Interface
• Stateless

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

14. REST
• Resource-Oriented
• Uniform Interface
• Stateless

16. Hi, for here or to go?
For here.
STATEFUL

17. What can I get you?
Can I have two cheeseburgers and one
order of fries?
STATEFUL

18. What size fries would
you like?
Small.
STATEFUL

19. Would you like
anything to drink?
I’ll have coke.
STATEFUL

20. Would you like
anything else?
No, I’m good.
STATEFUL

21. STATEFUL
• Cashier remembers your past orders
• You only have to put your latest order

22. Hi, for here or to go?
For here.
STATELESS

23. What can I get you?
For here.
Can I have two cheeseburgers and one
order of fries?
STATELESS

24. What size fries would
you like?
For here.
Can I have two cheeseburgers and one
order of fries?
Small.
STATELESS

25. Would you like
anything to drink?
For here.
Can I have two cheeseburgers and one
order of fries?
Small.
I’ll have coke.
STATELESS

26. STATELESS
• Cashier DOES NOT remember your past orders
• You have to put orders including past orders

27. STATELESS
• Cashier DOES NOT remember your past orders
• You have to put orders including past orders
What good will come of it? 🤔

28. STATELESS
• It was said that the main advantage of STATELESS was
SCALABILITY in the past
• It was believed that STATEFUL COULD NOT scale out

29. 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!

30. Agenda
• What is REST?
• How should we design practical
APIs?
• Conclusion

31. PRACTICAL … ?

32. Practical
• Dictionary says
• involving activity rather than study or theory
• likely to be successful or useful

33. Practical
SHU-HA-RI is a Japanese martial art
concept, and describes the stage of
learning to mastery

34. Practical
Repeat the forms and discipline ourselves
to absorb the forms and to find the values
lurking behind them
SHU → obey, protect

35. Practical
Based on the fundamentals learned with
break the forms and make innovation
HA → detach
,

36. Practical
Completely depart from the forms, act in
accordance with what we want
RI → leave

37. Practical
Find the key to PRACTICAL hiding around
here

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

39. 3 Questions
Reaching Practical
Design

40. Q.1
How should we design
the ENDPOINT to get our own
information?

41. GET /customers/:id
From GET method, easy to expect retrieving the customer
information from customers table while requesting
Anyone CAN GUESS other’s endpoints

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

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

44. 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!

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

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

47. Q.2
How should we design
the RESOURCE and the ENDPOINT
that allow customers to agree with
the Terms of Service?

48. Q.2
How should we design
the RESOURCE and the ENDPOINT
that allow customers to agree with
the Terms of Service?

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

50. 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
:

51. Q.2
How should we design
the RESOURCE and the ENDPOINT
that allow customers to agree with
the Terms of Service?

52. :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

53. Learned from Q.2
• SHOULD maximize representation of a
resource
• SHOULD make an Endpoint semantic

54. Q.3
How should we design
the SEQUENCE in which customers
buy something in an application?

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

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

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

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

59. Agenda
• What is REST?
• How should we design practical
APIs?
• Conclusion

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

61. Learned from Q.2
• SHOULD maximize representation of a
resource
• SHOULD make an Endpoint semantic

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

63. Thank you