This is a presentation about RESTful Web API Design. First Presented at the Backend Developers Meetup in Orlando on April 19th, 2018.

1. RESTful Design: Illustrated
Tommy Lee

2. Presentation Itinerary
We’ll learn basics of how to REST stuff.
First we’ll go over definitions that we use for REST.
Then We’ll go over examples of how a RESTful API might be designed.
Finally We’ll look at challenges we run into designing RESTful APIs

3. What is REST?
● REpresentational State Transfer (REST) is an architectural style that defines a
set of constraints and properties based on
● Client – Server architecture
● Uniform Interface
● Statelessness
● Gives client ability to interact with application without prior
knowledge of how to interact.

4. Let’s go Shopping
We’re going to visit an ecommerce API built in a RESTful fashion.

5. https://toys4.us/api/v1

6. Building a Request - REST

7. Initial Request
https://toys4.us/api/v1/
• /carts – shopping carts
• /checkout – checkout an order
• /products – list of products
• /wishlist – wishlists

9. Sending a REQUEST – RPC Style

10. Building a Request – RPC Style
● Step 1. Check the documentation.
OK Documentation Better Documentation

11. Building a Request – RPC Style
● Step 2. Build request as per documentation

12. Building a Request – RPC Style
● Step 3: Hope the documentation was up to date.

13. Breaking Down a Request

14. Breaking Down a Request
Action

15. Breaking Down a Request
Action Resource

16. Action – Verbs that do things
● GET – Retrieve a Resource
● POST – Create a new resource
● PUT- Replace a Resource
● PATCH – Edit part of a resource
● DELETE – Remove a resource
● OPTIONS – See what methods can be sent
● HEAD – Peek at a GET Request, no body.

17. Action - Verbs
GET Look
POST Make
PUT Replace
PATCH Edit
DELETE Delete

18. Resources - Nouns
Nouns represent stuff.
- Products
- cart
- toys
- Dolls
- Amount

19. Breaking Down a Request
Action Resource

20. Breaking Down a Request
Action Resource

21. Breaking Down a Request
Action Resource

22. Subresources
Sub resources are considered things that have a
relationship with the other thing.

23. Responses
Responses are sent back have a status code, and a message (body).
Status codes are based on standard HTTP status codes.
Body could be in any format, usually but not limited to JSON, XML, HTML.
Body could also include additional instructions for the user to interact with the state
of the object.

24. HTTP Status Codes
● Status Codes gives us a basic idea of how our REQUEST went and what we
should do.
1xx Informational
2xx Success
3xx Redirection
4xx Client Error
5xx Server Error

26. Create a new Wishlist
Status: 201 Created
Location:

27. Adding Items to Wishlist
● Visit the aisle with the item we want. Then we add it to the Wish list
200 OK
ID: 95

28. Adding Item to Wishlist (POST)
ID: 95
QTY: 2
QTY: 2
201 Created
QTY: 2

29. Adding Item to Wishlist (POST)
ID: 5
QTY: 1
QTY: 2
201 Created
QTY: 1QTY: 2 QTY: 1

30. Adding Item to Wishlist (POST)
ID: 5
QTY: 1
QTY: 2
201 Created
QTY
: 2
QTY: 2 QTY: 2

31. Changing Items to Wishlist (PUT)
ID: 32
QTY: 1
QTY: 2
200 OK
QTY: 1QTY: 2 QTY: 1

32. Changing Items to Wishlist (PATCH)
ID: 32
QTY: 10
QTY: 2
200 OK
QTY: 10
QTY: 2 QTY: 10

33. Removing Items from the Wishlist
QTY: 2
QTY: 2
200 OK
QTY: 0

34. Common Challenges

35. #1. Using GET for state-changing operations
● GET is considered a safe operation.
● Don’t do this: (The Money means purchase)
Instead, maybe do this?

36. #2. Sending wrong Status Code on Response
200 OK
But everything
was not
200 OK

37. Source: homestarrunner.com

39. #3: Keeping State in the Server
● Server doesn’t know specific state
● State of the application should be on the client.
● Client sends over everything necessary for the
request.

40. #3: Keeping State in the Server: Pagination
● Server should NOT remember what page you’re on.
VS.

41. #4: Having Actions in Resources
REST sometimes is hard since we don’t have enough verbs. So we might do this

42. #4: Having Actions in Resources
1. Try to break out items into better concepts?
Set actions as subresources
i. POST /products/:id/recommendations
ii. POST /layaways/

43. #4: Having Actions in Resources
Some items have state changes that are complex to model.
1. POST /orders/:id/process
2. POST /orders/:id/fulfill
3. POST /orders/:id/hold
4. POST /orders/:id/cancel

44. #4: Having Actions in Resources
● Some concepts just ain’t easy to turn into a noun, or naturally map to a RESTful
Resource
● POST /products/search

45. #4: Having Actions in Resources
● Possible Solution:
Have excellent
documentation

46. #4: Having Actions in Resources
● Possible Solution: Give the client instructions.

47. Hypermedia as the Engine of Application State
(HATEOAS)
● We can list the available commands available for a resource
as part of the RESPONSE.
● This gives no expectations for a client to use.
● Much like how a current website works with links.

48. Leveraging HATEOAS
links: {
fulfill: “/orders/55/fulfill”,
process: “/orders/55/process”,
hold: “/orders/55/hold”,
cancel: “/orders/id:/cancel”
}

49. When not to REST

50. Areas where REST could be hard
● Bandwidth limited clients (mobile)
○ Look into limiting fields or something like GraphQL
● Designs that have a lot of events and actions
○ Look at RPC style designs.
● You need server to remember state.
● We could be pragmatic, could use multiple designs

51. Thank You!

52. Sources and additional reading
● http://www.restapitutorial.com/lessons/httpmethods.html
● https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
● http://restcookbook.com/Basics/hateoas/
● https://blog.apisyouwonthate.com/understanding-rpc-rest-and-graphql-
2f959aadebe7
● https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
● http://restful-api-design.readthedocs.io/en/latest/relationships.html#standard-
structural-relationships
● Icons by Facebook