HTTP API Design Guide


API Design

Global design

General considerations on API design

API Lifecycle

Updates and Versioning

How to handle API updates and versioning

Collection Resources


How to retrieve a range of resources in a collection

Error handling

Error format

How to provide information about errors

HTTP Protocol


How to use and provide relevant caching informations

HTTP Headers

How to use standard or custom HTTP headers

HTTP Statuses

General information about HTTP statuses usage

HTTP Status Server Error

500 Internal Server Error

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

HTTP Status Success

200 OK

Standard 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 Created

The request has been fulfilled, resulting in the creation of a new resource.

202 Accepted

The 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 Content

The 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 Unauthorized

Similar 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 Forbidden

The 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 Entity

The request was well-formed but was unable to be followed due to semantic errors.

429 Too Many Requests

The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.


Debug and diagnose

How to provide informations to debug and diagnose


How to produce and/or propose API documentation

Performance and bandwidth

How to deal with high traffic or consumers with low bandwith

Rate limiting

How to provide information about how many calls a consumer can do



Which case (lowercase, camelCase, …) to use and when


How to name things


Action resource

How to use action resource (e.g. resources like /cancel or /approve)

Create resource

How to create resources

Delete resource

How to delete resources

ID with semantic

Using meaningful ids (like me)

Resource ID

What is a resource ID and/or how it’s built


How to define and use relations between resources

Retrieve resource

How to retrieve a resource

Update resource

How to update a resource

URL format

How to design URLs



Security concerns