REST Methodologies


Published on

Discusses many topics and best practices used today in REST development

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

REST Methodologies

  1. 1. Knowledge ShareREST MethodologiesJune 19, 2013
  2. 2. Topics• High level on REST• Richardson Maturity Model•Bulk of today’s session• Etc•Data Formats, Caching, Versioning, Discovery, Security• Q&A
  3. 3. What is REST?• REST is an architectural constraint based on HTTP 1.1, andcreated as part of Roy Fielding’s doctoral dissertation in 2000• It embraces HTTP• It’s not a style, not a standard
  4. 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 itsscore is.• 4 levels of increasing compliance• Level 3 designates a “truly” RESTful API
  5. 5. Level 0: Swamp of POX• POX = Plain Old XML• uses a transport protocol merely for tunneling. No propertiesof the transfer protocol is used, and all work is done throughthis tunnel.• Typically uses only one entry point (URI) and one kind ofmethod (in HTTP, this normally is the POST method).• Examples: SOAP and XML-RPC
  6. 6. 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 aspecific resource.• Examples:• /article/1 vs /article/2• /articles• Still, this level uses only one single method like POST• /articles/create_new
  7. 7. 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
  8. 8. 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
  9. 9. 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>
  10. 10. Modifying Multiple Resources• Want to tackle write operations that involve modifying morethan 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
  11. 11. Level 2: HTTP Verbs• indicates that your API should use the transport protocolproperties in order to deal with scalability and failures• Dont use a single POST method for all, but make use of GETwhen you are requesting resources, and use the DELETEmethod when you want to delete a resources• Use HTTP response codes properly• Dont return 200 (OK) when something went wrong.• Use HTTP headers properly
  12. 12. 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
  13. 13. 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
  14. 14. 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
  15. 15. 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
  16. 16. 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
  17. 17. 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)
  18. 18. 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 clientsand other tools, such as debuggers and test clients• Last-Modified
  19. 19. Level 3: Hypermedia ControlsThe level where most fall down. There are two parts to this:Content negotiation• focused on different representations of a particular resourceHATEAOS• = 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
  20. 20. HATEAOSLinks• Provide navigation from a given resource• Dynamic, based on resource state<link href=“/user/232/customers” rel=“customers” />
  21. 21. Linking{“links”: *{“rel”: “self”“href”: “…”},{“rel”: “alternate”“href”: “…”}{“rel”: “previous”“href”: “…”}}
  22. 22. 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: “”• prev: “”• next: “”• articles: { }
  23. 23. 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-]
  24. 24. Data Formats• Dates, times, numbers, currencies, etc.• Choosing portable formats for human readability and avoidinteroperability 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
  25. 25. 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
  26. 26. 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
  27. 27. 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
  28. 28. 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)
  29. 29. 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
  30. 30. SecurityIf service trusts clientBasic AuthDigest AuthOtherwiseOAuth
  31. 31. ReferencesRoy Thomas Fielding, Architectural Styles and the Design of Network-based Software Architectures, Web Services Cookbook, Subbu AllamarajuHaters gonna HATEOAS,
  32. 32. Q&A