6 ms·

The Heroku platform team has a good document about their API design guidelines: https://github.com/interagent/http-api-design https://github.com/interagent/htt

• iamdanfox 12y ago
  That is a very comprehensive set of conventions! Contents pasted here: 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