Successfully reported this slideshow.

Reviewing RESTful Web Apps

5,366 views

Published on

Reviewing RESTful Web Apps
at RESTful Meetup vol.3 (#RWABookja)
Apr 12, 2014

Published in: Technology, Design
  • Be the first to comment

Reviewing RESTful Web Apps

  1. 1. Reviewing RESTful Web Apps Takuto Wada (a.k.a id:t-wada or @t_wada) Apr 12, 2014 @ RESTful Meetup
  2. 2. Takuto Wada id: t-wada @t_wada github: twada
  3. 3. tl;dr: REST is infection (Use it, love it, but think carefully.)
  4. 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. 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. 6. •Large Rails Project •+1000 routes •Tools for reviewing •White board •Chat (IRC, Skype, ...) •Wiki •diff Target Project
  7. 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. 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. 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. 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. 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. 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. 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. 14. • Resources are not only Database Records. • Transactions • Calculation Results • Search Results Resources ≠ Database Records
  15. 15. •Simple and automatic mapping looks nice •GET/POST/PUT/DELETE •SELECT/INSERT/UPDATE/DELETE •It s a trap! The Gravity of CRUD
  16. 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. 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. 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. 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. 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. 21. •Mapping Errors to 4xx or 5xx •Models just raise Errors •Rails maps them •Want to hide resources => use 404 HTTP Status Code
  22. 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. 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. 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. 25. •Client can only change its application status by following links (or submitting forms) in representations served by servers For the Connectedess
  26. 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. 27. References
  28. 28. tl;dr: REST is infection (Use it, love it, but think carefully.)
  29. 29. Thanks! http://lumberjaph.net/graph/2010/03/25/github-explorer.html

×