ReviewingRESTful Web Apps

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

Takuto Wadaid: t-wada@t_wadagithub: twada

tl;dr:REST isinfection

(Use it, love it, but think carefully.)

•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)

• 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)

•Large Rails Project• +1000 routes

•Tools for reviewing•White board

• Chat (IRC, Skype, ...)

•Wiki

• diff

Target Project

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

•URL Design (verb, structure, query params)

• fighting with the gravity of CRUD

•HTTP method

•HTTP status code

• Representation

•MECE of information

• Connectedness

Review point

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

• /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

• 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?

• 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

• 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

• Resources are not only Database Records.

• Transactions

• Calculation Results

• Search Results

Resources ≠ Database Records

• Simple and automatic mapping looks nice

•GET/POST/PUT/DELETE

• SELECT/INSERT/UPDATE/DELETE

•It’s a trap!

The Gravity of CRUD

•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

•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

•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

• 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

• 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

•Mapping Errors to 4xx or 5xx

•Models just raise Errors

• Rails maps them

•Want to hide resources => use 404

HTTP Status Code

• 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

• 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

•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

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

For the Connectedess

•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

References

tl;dr:REST isinfection

(Use it, love it, but think carefully.)

Thanks!

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