White House Web API Standards

White House

API Lifecycle

Versioning

How to handle API versioning

Collection Resources

Filtering

How to select some resources in a collection

Error handling

Error format

How to provide information about errors

HTTP Methods

POST

The POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. The data POSTed might be, for example, an annotation for existing resources; a message for a bulletin board, newsgroup, mailing list, or comment thread; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database.

HTTP methods

General information about HTTP methods usage

GET

The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect.

DELETE

The DELETE method deletes the specified resource.

PUT

The PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI.

HTTP Protocol

HTTP Statuses

General information about HTTP statuses usage

HTTP Headers

How to use standard or custom HTTP headers

Content negociation and media types

How to describe your API data format and/or propose different formats (like json, yaml, xml atom, …)

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.

HTTP Status User Error

400 Bad Request

The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, too large size, invalid request message framing, or deceptive request routing).

Miscellaneous

CORS

How to deal with CORS

Naming

Naming

How to name things

Resources

Delete resource

How to delete resources

Batch Bulk

How to handle batch/bulk processing/creation/update/… (e.g. handle multiple resources at conce)

Retrieve resource

How to retrieve a resource

Update resource

How to update a resource

URL format

How to design URLs

Create resource

How to create resources