Knowledge ShareREST Methodologies

June 19, 2013

Topics• High level on REST• Richardson Maturity Model•Bulk of today’s session

• Etc•Data Formats, Caching, Versioning, Discovery, Security

• Q&A

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_transferhttp://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

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

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

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

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

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

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

snapshot>

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

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

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

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

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

Status CodesConvey the result of the server’s attempt to satisfy the request

• 1xx: informational• 2xx: success• 3xx: redirection• 4xx: client error• 5xx: server error

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

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)

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

Level 3: Hypermedia ControlsThe 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

HATEAOSLinks• Provide navigation from a given resource• Dynamic, based on resource state

<link href=“/user/232/customers” rel=“customers” />

Linking{

“links”: [{

“rel”: “self”“href”: “…”

},{

“rel”: “alternate”“href”: “…”

}{

“rel”: “previous”“href”: “…”

}}

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: { }

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}

]

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

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

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

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

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)

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

SecurityIf service trusts clientBasic AuthDigest Auth

OtherwiseOAuth

ReferencesRoy 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-springhttp://bestoked.blogspot.com/2012/02/restful-resources-required-reading.htmlhttp://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.htmlhttp://www.informit.com/articles/article.aspx?p=1566460http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-httphttp://stackoverflow.com/questions/389169/best-practices-for-api-versioninghttps://blog.apigee.com/detail/restful_api_design_how_many_versions

Q&A