HTTP API Design
Introduction
1.
Foundations
1.1.
Separate Concerns
1.2.
Require Secure Connections
1.3.
Require Versioning in the Accepts Header
1.4.
Support ETags for Caching
1.5.
Provide Request-Ids for Introspection
1.6.
Divide Large Responses Across Requests with Ranges
2.
Requests
2.1.
Accept serialized JSON in request bodies
2.2.
Resource names
2.3.
Actions
2.4.
Use consistent path formats
2.4.1.
Downcase paths and attributes
2.4.2.
Support non-id dereferencing for convenience
2.4.3.
Minimize path nesting
3.
Responses
3.1.
Return appropriate status codes
3.2.
Provide full resources where available
3.3.
Provide resource (UU)IDs
3.4.
Provide standard timestamps
3.5.
Use UTC times formatted in ISO8601
3.6.
Nest foreign key relations
3.7.
Generate structured errors
3.8.
Show rate limit status
3.9.
Keep JSON minified in all responses
4.
Artifacts
4.1.
Provide machine-readable JSON schema
4.2.
Provide human-readable docs
4.3.
Provide executable examples
4.4.
Describe stability
Published with GitBook
HTTP API Design
Foundations
The Foundations section outlines the design principles upon which the rest of the guide builds.