Discusses many topics and best practices used today in REST development

1. Knowledge Share
REST Methodologies
June 19, 2013

2. Topics
• High level on REST
• Richardson Maturity Model
•Bulk of today’s session
• Etc
•Data Formats, Caching, Versioning, Discovery, Security
• Q&A

3. What is REST?
• REST is an architectural constraint based on HTTP 1.1, and
created as part of Roy Fielding’s doctoral dissertation in 2000
• It embraces HTTP
• It’s not a style, not a standard
http://en.wikipedia.org/wiki/Representational_state_transfer
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

4. Richardson Maturity Model
…since few REST implementators read Fielding’s thesis
• a way to grade your API according to the REST constraints.
• the better your API adheres these constraints, the higher its
score is.
• 4 levels of increasing compliance
• Level 3 designates a “truly” RESTful API

6. Level 0: Swamp of POX
• POX = Plain Old XML
• uses a transport protocol merely for tunneling. No properties
of the transfer protocol is used, and all work is done through
this tunnel.
• Typically uses only one entry point (URI) and one kind of
method (in HTTP, this normally is the POST method).
• Examples: SOAP and XML-RPC

7. Level 1: Resources
• When your API can distinguish between different resources,
it might be level 1.
• Uses multiple URIs, where every URI is the entry point to a
specific resource.
• Examples:
• /article/1 vs /article/2
• /articles
• Still, this level uses only one single method like POST
• /articles/create_new

8. URI Design
• Slashes – hierarchical
• /user/JROD/friends (“ah, this returns a list of JROD’s friends”)
• Hyphens or underscores – readability (preferred: hyphens)
• /notAGoodWay
• /a_better_way
• /the-preferred-way
• Query String – Filtering: ?, &, =
• Semicolons: Matrix parameters, hierarchial, categorical
 /reports/some-report/date/2009-03/sort-by/email
• Returns email? date? report?
 /reports/some-report?date=2009-03&sort-by=email

9. Collection Resources
• “Plurals”
• /users
• /users/JROD/friends
• Used for
• Paginated views
• Filtered views
• Create new member resources
• Friend request => POST /users/JROD/friends
• Perform same operation on multiple resources

10. Composite Resources
• Combines information from other resources
• Approach #1
• => GET /customer/1234
• => GET /customer/1234/orders?sort_by=date&limit=10
• => GET /customer/1234/quotes?sort_by=date&limit=10&status=pending
• Great for modular design, bad for network (chatty)
• Can we minimize network overhead without compromising REST?
• Approach #2
• => GET /customer/1234/snapshot
• <=
<snapshot><customer>..</customer><orders>..</orders><quotes>..</quotes></snaps
hot>

11. Modifying Multiple Resources
• Want to tackle write operations that involve modifying more
than one resource atomically?
• RESTful controllers
• If creating a single resource <= 201 Created, Location
• If modifying 1+ resources <= 303 See Other, Location
• If more than one Location <= 200 OK, Body: all Locations
• Errors

12. Level 2: HTTP Verbs
• indicates that your API should use the transport protocol
properties in order to deal with scalability and failures
• Don't use a single POST method for all, but make use of GET
when you are requesting resources, and use the DELETE
method when you want to delete a resources
• Use HTTP response codes properly
• Don't return 200 (OK) when something went wrong.
• Use HTTP headers properly

13. HTTP Verbs
• GET /user/21  retrieves a resource from a URI
• DELETE /user/21  removes the resource
• POST /users  creates a new record; returns Location
• PUT /user/21  updates a resource

14. PUT vs POST
• Some literature seemingly use POST or PUT interchangeably
• When do you use PUT vs POST?
• POST
• URL is decided by server
• Response: 201 Created & Location header
• If full representation in response, add Content-Location header
• PUT
• URL decided by client
• Response: 201 Created
• Preference: PUT for updates, POST for creates

15. Asynchronous Tasks
• Some requests take time to complete
• Creates (POST), deletes (DELETE)
• Multithreaded AJAX controllers can hang!
• How to handle?
• => POST /imgs/tasks
• <= 202 (Accepted), Content-Location: /imgs/task/1, Body: “got it!”
• => GET /imgs/task/1
• (still processing) <= 200 (OK), Body: “still processing!”
• (done) <= 303 (See Other), Location: /imgs/1, Body: “done!”
• (failed) <= 200 (OK), Body: “error reason”
• Why 200 on fail? Because task succeeded, image did not

16. Status Codes
Convey the result of the server’s attempt to satisfy the request
• 1xx: informational
• 2xx: success
• 3xx: redirection
• 4xx: client error
• 5xx: server error

17. Error Codes
• Client errors
• 400 (Bad Request) – missing required HTTP packet info
• 401 (Unauthorized) – can be fixed if authenticated
• 403 (Forbidden) – don’t try again, can’t access
• 404 (Not Found) – never existed or deleted
• 405 (Not Allowed) – HTTP method not allowed
• 406 (Not Acceptable) – Requested media type not an option
• 409 (Conflict) – “request conflicts with current state of resource”
• 412 (Precondition Failed) – See conditional requests
• 413 (Request Entity Too Large) – POST or PUT request too big,
provide limit details
• 415 (Unsupported Media Type) – Sent media type not supported

18. Error Codes
• Server errors
• 500 (Internal Server Error)
• Generic; “uhoh, I missed something” = bug
• 503 (Service Unavailable)
• Database connection
• Rate limit
• Best practice: include Retry-After header
• All errors
• Include message in Body (unless method = HEAD)

19. Headers
• Content-Type
• Prefer to use well-known media types for representations
• application/json is the de facto standard for JSON responses
• Content-Type = MIME-Type = File format ≠ Schema
• Application-specific media types
• promote visibility provided that such media types are widely supported
• In general, should be avoided as they may reduce interoperability with clients
and other tools, such as debuggers and test clients
• Last-Modified

20. Level 3: Hypermedia Controls
The level where most fall down. There are two parts to this:
Content negotiation
• focused on different representations of a particular resource
HATEAOS
• = Hypermedia as the Engine of Application State
• No a priori knowledge of service required
• Discoverability of actions on a resource.
• Navigation options are provided by service and hypermedia controls
• Promotes longevity through a uniform interface

21. HATEAOS
Links
• Provide navigation from a given resource
• Dynamic, based on resource state
<link href=“/user/232/customers” rel=“customers” />

22. Linking
{
“links”: *
{
“rel”: “self”
“href”: “…”
},
{
“rel”: “alternate”
“href”: “…”
}
{
“rel”: “previous”
“href”: “…”
}
}

23. Pagination
• What to include in collection resources
• Links to self, next (if not at end), previous (if not at start)
• Size of collection
• Example
• => GET /articles?contains=cycling&start=10
• <= Body:
• total: 1921
• self: “http://foo.com/articles?contains=cycling&start=10”
• prev: “http://foo.com/articles?contains=cycling”
• next: “http://foo.com/articles?contains=cycling&start=20”
• articles: { }

24. Homogeneity
• Analogous to supertypes in Java collections
• aka don’t rely on Object

• products: [ car: {id, mpg}, boat: {id, hull}]

• products: [
product: ,id, type: “car”, make, model-
boat: ,id, type: “boat”, make, model-
]

25. Data Formats
• Dates, times, numbers, currencies, etc.
• Choosing portable formats for human readability and avoid
interoperability errors
• Countries & states: ISO-3166: (US, CA) vs. (US-NY, CA-BC)
• Currencies: ISO 4217: USD, CAD, JPY
• Locales: RFCs 5645, 5646: en-US, en-CA, ja-JP
• Dates & times: ISO 8601/RFC 3339
• String sortable/comparable
• Human readable (else use Unix epoch)
• UTC format prevents time zone issues
• E.g., 2013-06-19T11:26:00Z-5:00

26. Caching
• Expiration caching in HTTP done in two ways
• Expires (HTTP 1.0)
• Cache-Control (HTTP 1.1)
• Private, public, no-store, etc.
• Pragma: no-cache (HTTP 1.0)
• GET and HEAD requests only
• Consider adding caching headers to 3xx and 4xx errors!
• Client-side mechanism usually handled by user agent

27. Conditional Requests
• Servers
• Last-Modified
• Etag
• Clients
• Validating cached representations
• If-Modified-Since
• If-None-Match
• Preconditions for concurrency control
• If-Unmodified-Since
• If-Match
• One-Time URIs for POSTs

29. Transactions
• If REST is stateless, how do I support transactions?
• Provide a resource that can make atomic changes to data
• Treat uncommitted state as application state
• If supporting “undos”, use PUT, DELETE, POST as needed
• Asynchronous tasks if long-running

30. Extensibility & Versioning
• Adding attributes usually not a problem
• JSON (de)serialization basically uses a hashtable
• Clients will lookup values that they expect
• Deleting attributes is the problem
• changing JSON structure is a variant of this
• Array*“missing-key”+ = nada
• format(nada) = *crash*
• Options
• Media type (bad)
• URL (mixed review -> “URIs should remain permanent!”
• Query parameters (OK)
• Domain name (may be OK)

31. Documenting & Discovery
• Generic Document Template
• All Resources
• All allowed methods for each resource
• Supported media types
• Query Parameters
• URI templates and token definitions
• Role(s) required, if secured
• Link relations, if any
• Discovery
• OPTIONS method
• Supported by Jersey

32. Security
If service trusts client
Basic Auth
Digest Auth
Otherwise
OAuth

33. References
Roy Thomas Fielding, Architectural Styles and the Design of Network-based Software Architectures,
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
RESTful Web Services Cookbook, Subbu Allamaraju
Haters gonna HATEOAS, http://timelessrepo.com/haters-gonna-hateoas
http://www.slideshare.net/joshlong/rest-apis-with-spring
http://bestoked.blogspot.com/2012/02/restful-resources-required-reading.html
http://barelyenough.org/blog/2008/05/versioning-rest-web-services/
http://jacobian.org/writing/rest-worst-practices/
http://restcookbook.com/Miscellaneous/richardsonmaturitymodel/
http://martinfowler.com/articles/richardsonMaturityModel.html
http://www.informit.com/articles/article.aspx?p=1566460
http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http
http://stackoverflow.com/questions/389169/best-practices-for-api-versioning
https://blog.apigee.com/detail/restful_api_design_how_many_versions

34. Q&A