HTTP API Design Guide

Heroku

API Design

Global design

General considerations on API design

API Lifecycle

Versioning

How to handle API versioning

Collection Resources

Pagination

How to retrieve a range of resources in a collection

Error handling

Error format

How to provide information about errors

HTTP Protocol

Caching

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

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.

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.

201 Created

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

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.

HTTP Status User Error

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.

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.

Miscellaneous

Performance and bandwidth

How to deal with high traffic or consumers with low bandwith

Debug and diagnose

How to provide informations to debug and diagnose

Rate limiting

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

Documentation

How to produce and/or propose API documentation

Naming

Naming

How to name things

Case

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

Resources

Create resource

How to create resources

Delete resource

How to delete resources

Action resource

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

Resource ID

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

Relationships

How to define and use relations between resources

ID with semantic

Using meaningful ids (like me)

Update resource

How to update a resource

URL format

How to design URLs

Retrieve resource

How to retrieve a resource

Security

Security

Security concerns