HTTP API设计Guide

翻译自https://github.com/richzw/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

Todo list