API Style Guide


API Lifecycle

Updates and Versioning

How to handle API updates and versioning

Collection Resources


How to retrieve a range of resources in a collection

Retrieve a collection

How to get a collection or resources

Sorting a collection

How to sort a collection of resources


What is a collection (set) of resources


How to select some resources in a collection

HTTP Methods


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


The PATCH method applies partial modifications to a resource.

HTTP methods

General information about HTTP methods usage


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.


The DELETE method deletes the specified resource.


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 Protocol

HTTP Statuses

General information about HTTP statuses usage


How to use and provide relevant caching informations

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.

204 No Content

The server successfully processed the request and is not returning any content.

HTTP Status User Error

404 Not Found

The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.

422 Unprocessable Entity

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

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).



How to use hypermedia

Hypermedia (read)

How to use hypermedia to read data


Query parameters

How to use query parameters

Performance and bandwidth

How to deal with high traffic or consumers with low bandwith



How to name things


Create resource with a specific ID

How to create resource with a provided id

Create resource

How to create resources

Delete resource

How to delete resources

Batch Bulk

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

Action resource

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

Retrieve resource

How to retrieve a resource

Resource's state

How to change a resource’s state/status (like processed/sent/paid/…)

Update resource partially

How to udate partially a resource

Update resource

How to update a resource

URL format

How to design URLs


General informations about resources

Replace resource

How to replace (or update fully) a resource