HTTP API Design Guide
Heroku
API Design
Global designGeneral considerations on API design |
API Lifecycle
Updates and VersioningHow to handle API updates and versioning |
Collection Resources
PaginationHow to retrieve a range of resources in a collection |
Data
Date and TimeHow to deal with date and time data |
Data formatwhich data format use |
Error handling
Error formatHow to provide information about errors |
HTTP Protocol
CachingHow to use and provide relevant caching informations |
HTTP HeadersHow to use standard or custom HTTP headers |
HTTP StatusesGeneral information about HTTP statuses usage |
HTTP Status Server Error
500 Internal Server ErrorA generic error message, given when an unexpected condition was encountered and no more specific message is suitable. |
HTTP Status Success
200 OKStandard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action. |
201 CreatedThe request has been fulfilled, resulting in the creation of a new resource. |
202 AcceptedThe request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs. |
206 Partial ContentThe server is delivering only part of the resource (byte serving) due to a range header sent by the client. The range header is used by HTTP clients to enable resuming of interrupted downloads, or split a download into multiple simultaneous streams. |
HTTP Status User Error
401 UnauthorizedSimilar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource. |
403 ForbiddenThe request was a valid request, but the server is refusing to respond to it. The user might be logged in but does not have the necessary permissions for the resource. |
422 Unprocessable EntityThe request was well-formed but was unable to be followed due to semantic errors. |
429 Too Many RequestsThe user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes. |
Miscellaneous
Debug and diagnoseHow to provide informations to debug and diagnose |
DocumentationHow to produce and/or propose API documentation |
Performance and bandwidthHow to deal with high traffic or consumers with low bandwith |
Rate limitingHow to provide information about how many calls a consumer can do |
Resources
Action resourceHow to use action resource (e.g. resources like /cancel or /approve) |
Create resourceHow to create resources |
Delete resourceHow to delete resources |
ID with semanticUsing meaningful ids (like |
Resource IDWhat is a resource ID and/or how it’s built |
RelationshipsHow to define and use relations between resources |
Retrieve resourceHow to retrieve a resource |
Update resourceHow to update a resource |
URL formatHow to design URLs |
Security
SecuritySecurity concerns |