GlueCon 2013 Notes: Designing a Beautiful REST+JSON API – Les Hazlewood, CTO of Stormpath

Designing a Beautiful REST+JSON API – Les Hazlewood, CTO of Stormpath (@lhazlewood)

• REST is really hard (for providers)
• Guidelines and conventions can make it easy
• Resources are nouns, not verbs
• Should be course grained, not fine grained (or else the API will grow too large)
• Don’t do RPC-style (/getUser, /updateUser)
• HTTP verbs do not have to have a 1:1 correlation with create, read, update, delete
• GET = Read, DELETE = Delete, HEAD = Headers, no body
• PUT and POST can BOTH be used for create and update
• PUT can be used for create if the identifier/location is known by the client (e.g. /applications/clientSpecifiedId)
• PUT can be used for full replacement update (e.g. PUT /applications/existingId)
  • Must contain the full replacement, making it idempotent on the server (meaning that the same state is the result of multiple calls with the same payload)
• POST can be used for create on a parent resource (e.g. POST /applications) – return a 201 created and set the Location header to the URL
• POST can be used as an update (e.g. POST /applications/a1b2c3) – return a 200 OK
• Media Types provide format specification + parsing rules
  • Request: Accept header
  • Response: Content-Type header
  • application/json
  • application/foo+json
  • application/foo+json;application
  • Very important to nail this (was mentioned early in Fielding’s thesis)
• Base URLs matter and convey a good (or bad) feeling about the support of your API
• Versioning – URL or Media-Type (e.g. application/json_foo;application&v=1)
  • Media types for versioning isn’t obvious for new developers, but is more correct
• Resource Format can use the Media-Type (e.g. application/json_foo;bar=baz&v=1) but still in flux
• camelCase to support Javascript naming conventions and for easier consumption
• Timestamps – ISO 8601 using UTC
• HREF – distributed hypermedia is paramount!
  • Every accessible resource has a unique URL
  • Replaces IDs (IDs exist, but are opaque)
  • Critical for linking
• Response Body
  • GET is obvious, but what about POST?
  • Return the representation in the response when feasible
  • Add override (?_body=false) for control when payloads may be large or rate limiting based on size
• Header
  • Accept header, with values in order of preference
• Resource extensions
  • /applications/a1b2c3.json, .csv, etc. can override accepts
• Hypermedia is paramount, linking is fundamental to scalability (not to performance, but to data scale and object graphs)
  • Tricky in JSON, easy with XML (XLink)
  • Use ‘href’ to mimic ref attribute in HTML links
• Reference Expansion (aka Link Expansion or Entity Expansion)
  • Allows clients to control how much data they get back (e.f. x7y8z9?expand=directory)
  • Representation can expand on ‘href’ approach with additional data (or not) and client can handle appropriately
• Pagination
  • Offset/Limit (e.g. /accounts/x7y8z9/groups?offset=25)
• Many to Many
  • Mappings should be a resource (GroupMembership for Accounts<–>Groups), allowing for future metadata to the resource
• Errors
  • As descriptive as possible
  • As much information as possible
  • Developers are your customer
  • Properties recommended: status (409), code (40925), property name, message, developerMessage, moreInfo (URL to docs for error code)
• Security
  • Avoid server sessions
  • Use standards (OAuth2, Basic auth over SSL only)
• Longer talk online: http://stormpath.com/blog/designing-rest-json-apis