This document summarizes Takuto Wada's presentation on reviewing RESTful web apps. It discusses best practices for designing RESTful resources and representations, including using nouns instead of verbs in URLs, making URLs reflect the meaning of resources, and ensuring resources are connected through hypermedia links and forms. It also covers appropriate use of HTTP methods, status codes, and content negotiation to build RESTful APIs in accordance with best practices.

1. Reviewing
RESTful Web Apps
Takuto Wada (a.k.a id:t-wada or @t_wada)
Apr 12, 2014 @ RESTful Meetup

2. Takuto Wada
id: t-wada
@t_wada
github: twada

3. tl;dr:
REST is
infection
(Use it, love it, but think carefully.)

4. •WEB+DB PRESS vol.32
•Discussion around Hatena-Bookmark
•RubyKaigi 2006 Keynote by DHH
•WEB+DB PRESS vol.38
•RESTful Web Service
•RESTful Web APIs
REST and me (input)

5. •Java implementations (S2REST)
•WEB+DB PRESS vol.42 Experiencing
REST world with Restlet
• Practical REST talk series by gihyo
• #restwebtech book talk session
REST and me (output)

6. •Large Rails Project
•+1000 routes
•Tools for reviewing
•White board
•Chat (IRC, Skype, ...)
•Wiki
•diff
Target Project

7. 1. Figure out the data set
2. Split the data set into resources
For each kind of resource:
3. Name the resources with URIs
4. Expose a subset of the uniform interface (GET/POST/PUT/DELETE)
5. Design the representation(s) accepted from the client
6. Design the representation(s) served to the client
7. Integrate this resource into existing resources, using hypermedia
links and forms (Connectedness matters)
8. Consider the typical course of events: what s supposed to happen?
9. Consider error conditions: what might go wrong?
Turning Requirements into Resources

8. •URL Design (verb, structure, query
params)
•fighting with the gravity of CRUD
•HTTP method
•HTTP status code
•Representation
•MECE of information
•Connectedness
Review point

9. Bad GET http://example.com/blog/getEntries
Good GET http://example.com/blog/entries
Bad POST http://example.com/blog/entries/add
Good POST http://example.com/blog/entries
Bad POST http://example.com/blog/entries/30/delete
Good DELETE http://example.com/blog/entries/30
Do not include verbs in URL

10. •/add, /delete, /update => Bad
•/edit => it depends (convention matters)
•Trying to use nouns
•/confirm -> /confirmation
•When the form of noun and verb are the
same => it depends
Do not include verbs in URL

11. • Tumblr s Bizarre URL => Too Bad
• http://www.tumblr.com/show/everything/by/me
• Reads like spoken language doesn t matter
• example.com/files/copy/:src/:dest => Bad
• destination is not subordinated to source
• Are they natural subordinates/subsets ?
Is your URL natural?

12. • URL Design is about searching for good names
• standard names (microformats, W3C, ...)
• dictionary, thesaurus, ...
• Find the third resource , the resource representing
relationship between resources.
• subscription, participation, ...
• Finally, ing s. belonging, tagging, ...
Searching for names

13. • What is it? => Meaning
• How do I get it? => Will
• Meaning shouldn t change even if query
parameters are removed.
• URL fragments should be composed of
meaningful names.
Meaning and Will in URL
http://example.com/blog/entries?page=3&lang=ja
Meaning of the Resource Will of client

14. • Resources are not only Database Records.
• Transactions
• Calculation Results
• Search Results
Resources ≠ Database Records

15. •Simple and automatic mapping looks nice
•GET/POST/PUT/DELETE
•SELECT/INSERT/UPDATE/DELETE
•It s a trap!
The Gravity of CRUD

16. •Why trap?
•Importance of models/tables varies.
•Core Domain Models tend to have many
more meanings and representations.
•In contrast, some tables are just
dependent tables. So they don t have
their own representations.
The Gravity of CRUD

17. •Don t just map 3NF tables to resources
•Some of them are too fine-grained
•N+1 Problem appears!
•Routes and Controllers should:
•Fill the gap of granularity and viewpoint
between Resources and Tables.
•Map them if and only if it is meaningful.
The Gravity of CRUD

18. •What do you want to do to the Resource?
•get it => GET
•create new one => POST
•modify it => UPDATE / PATCH
•delete it => DELETE
HTTP Methods

19. •Contents is the king and so HTTP GET is
the king.
•To make Resources:
•new Resource with new URL => POST
•URL is known/given => PUT
•If in doubt, use POST
HTTP Methods

20. •Status codes regularly used
•200, 201, 204
•301, 303, 307, (304)
•400, 404, 409, (401, 403, 422 (rails))
•500
•Client is wrong => 4xx
•Server is wrong => 5xx
HTTP Status Code

21. •Mapping Errors to 4xx or 5xx
•Models just raise Errors
•Rails maps them
•Want to hide resources => use 404
HTTP Status Code

22. •Should contain URL or URL
creator(forms)
•No dead-ends
•If you want to construct GET query
parameters
•use forms
•forms are not only for POST
requests
Representation

23. •Content Negotiation
•use Accept, Accept-Language
•Better to include representation
formats in URL (fragments,
extensions)
•more better to include languages
(ja,en,...) in URL
Representation

24. •Don t concat strings to create URL on
the client side!
•Client shouldn t know how to
construct URLs
•use URI-Templates
•http://tools.ietf.org/html/rfc6570
Representation

25. •Client can only change its
application status by
following links (or submitting
forms) in representations
served by servers
For the Connectedess

26. •Services should not enforce clients to
construct URL
•Services should not expect clients to
construct URL
•Services should serve representations
with links(forms) for next application
state transitions
For the Connectedess

27. References

28. tl;dr:
REST is
infection
(Use it, love it, but think carefully.)

29. Thanks!
http://lumberjaph.net/graph/2010/03/25/github-explorer.html