Apply best practices for API Design

[dmcinnes]

Need to look at this and create issues for each:
https://github.com/interagent/http-api-design

• Foundations
  • Require TLS
  • Version with Accepts header
  • Support caching with Etags
  • Trace requests with Request-Ids
  • Paginate with ranges
• Requests
  • Return appropriate status codes
  • Provide full resources where available
  • Accept serialized JSON in request bodies
  • Use consistent path formats
  • Downcase paths and attributes
  • Support non-id dereferencing for convenience
  • Minimize path nesting
• Responses
  • Provide resource (UU)IDs
  • Provide standard timestamps
  • Use UTC times formatted in ISO8601
  • Nest foreign key relations
  • Generate structured errors
  • Show rate limit status
  • Keep JSON minified in all responses
• Artifacts
  • Provide machine-readable JSON schema
  • Provide human-readable docs
  • Provide executable examples
  • Describe stability

From this list here are the identified todos:

• I know ~~~request ID and~~~ pagination (ranges) definitely for 1.0.0

• Examine how to implement: Etags, Caching (plugin), Rate Limiting (plugin) mechanisms

• For "Use consistent path formats" -- we could add a mechanism for "actions"

• Patch Rails to allow dashes in routes, converting them to underscores in controller lookup.

• Return full resource in update and delete actions; ensure ActiveResource doesn't complain

• Consider adding created_at, updated_at as default read_only attributes

• Support non-id dereferencing for convenience, for example /zones/ewr1.json:

  class ZoneController < APIController
    find_by :code, :uuid
  end

• Nest foreign key relations should be investigated.

• Consider adding id, url to structured errors; url points back to auto-generated doc in the API

[dmcinnes]

moved from https://github.com/att-cloud/daylight/issues/28