Reviewing RESTful Web Apps

Reviewing RESTful Web Apps

• 1.
  Reviewing RESTful Web Apps TakutoWada (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 •Discussionaround 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+DBPRESS 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 •+1000routes •Tools for reviewing •White board •Chat (IRC, Skype, ...) •Wiki •diff Target Project
• 7.
  1. Figure outthe 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 GoodGET 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 sBizarre 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 Designis 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 isit? => 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 arenot only Database Records. • Transactions • Calculation Results • Search Results Resources ≠ Database Records
• 15.
  •Simple and automaticmapping looks nice •GET/POST/PUT/DELETE •SELECT/INSERT/UPDATE/DELETE •It s a trap! The Gravity of CRUD
• 16.
  •Why trap? •Importance ofmodels/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 justmap 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 youwant to do to the Resource? •get it => GET •create new one => POST •modify it => UPDATE / PATCH •delete it => DELETE HTTP Methods
• 19.
  •Contents is theking 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 regularlyused •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 to4xx or 5xx •Models just raise Errors •Rails maps them •Want to hide resources => use 404 HTTP Status Code
• 22.
  •Should contain URLor 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 concatstrings 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 onlychange its application status by following links (or submitting forms) in representations served by servers For the Connectedess
• 26.
  •Services should notenforce 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