Introduction
1.
Foundations
1.1.
REST
1.2.
Separate Concerns
1.3.
Require Secure Connections
1.4.
Allow Versioning in the URL
1.5.
Support ETags for Caching
1.6.
Provide Request-Ids for Introspection
2.
Requests
2.1.
Accept serialized JSON in request bodies
2.2.
Resource names
2.3.
Actions
2.4.
Hierarchical data
2.5.
Use consistent path formats
2.5.1.
Paths and attributes case
2.5.2.
Support non-id dereferencing for convenience
2.5.3.
Minimize path nesting
2.6.
Collection requests
2.6.1.
Sorting
2.6.2.
Filtering
2.6.3.
Pagination
2.7.
Sparse fieldsets
3.
Responses
3.1.
Resource objects
3.1.1.
Provide resource (UU)IDs
3.1.2.
Type field
3.1.3.
Provide full resources where available
3.2.
Enveloping
3.3.
Relationship population
3.4.
Link objects
3.5.
Return appropriate status codes
3.6.
Generate structured errors
3.7.
Keep JSON minified in all responses
3.8.
Provide standard timestamps
3.9.
Use UTC times formatted in ISO8601
3.10.
Show rate limit status
4.
Artifacts
4.1.
Provide machine-readable JSON schema
4.2.
Provide human-readable docs
4.3.
Provide executable examples
Published with GitBook
A
A
Serif
Sans
White
Sepia
Night
Share on Twitter
Share on Google
Share on Facebook
Share on Weibo
Share on Instapaper
REST API Recommendations
Provide machine-readable JSON schema
Provide a machine-readable
JSON schema
to exactly specify your API.