The document provides an overview of REST methodologies and the Richardson Maturity Model. It discusses the four levels of the Richardson Maturity Model - from level 0 where only one entry point and method are used, to level 3 where hypermedia controls and content negotiation are implemented. The bulk of the document focuses on best practices for designing RESTful APIs, including URI design, HTTP verbs, status codes, conditional requests, caching, security, and versioning. It concludes with references for further reading.

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