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