API Design Guide

• Preface to the API Design Guide
• Copyright
• Principles
  • Developer empathy
  • Granularity
  • Functionality
  • Ubiquitous standards
  • Special circumstances
  • Community standards
  • Clear error messages
  • Endpoint stability
  • Privacy and security
  • Documentation
  • Dogfooding
• Building and using APIs
  • Use RESTful service URLs
  • Use HTTP methods and status codes
  • Use versions
  • Batching results
  • Mock behaviour
  • Support cross-domain mashups with CORS
  • Management state with HATEOAS
  • Document your API
  • Register your API
• Secure APIs
• Operate and improve APIs

RFC 2119 keywords

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.