REST API Design Guidelines

Leonard Richardson analyzed a hundred different web service designs and divided them into four categories based on how much they are REST compliant.

Every good RESTful API is resource based. A resource is a representation of a domain entity for clients. Ideally, all resources represent the domain of the API. A resource should therefore fulfill the following points:

The very first step in designing a REST API based application is – identifying the objects which will be presented as resources. Resources should be defined to cover 90% of all its client’s use cases. A useful resource should contain as much information as necessary, but as little as possible. A resource can be a collection or a singleton. For example, "customers" is a collection resource and "customer" a singleton resource. A collection resource can be identified using the Uniform Resource Name (URN) e.g:

A singleton resource can be identified using the URN e.g:

A resource may contain sub-collection resources. For example "accounts" of a particular "customer" can be identified using the URN:

A specific account for a particular customer can be identified via URN as follows:

For security and data protection reasons it is advisable that the identifier is not enumerable or easy to guess. It must not contain personal or private data (URLs appear in access logs, browser history,…​). The type of identifier should not allow attackers or competitors to make inferences about the system (enumeration attacks). For practical reasons the identifier should not be subject to change.

Common type of identifiers:

Further reading:

HTTP defines a set of request methods to indicate the desired action to be performed for a given resource. Be compliant with the standardized HTTP method semantics summarized as follows:

If you cannot avoid versioning use the following best practices:

To identify the version of the API a three number semantic versioning restricted to the format <MAJOR><MINOR><PATCH> for versions as follows is recommended:

*breaking changes are backwards-incompatible changes

JSON is the standard for transferring data, so REST APIs should accept JSON for request payload and also send responses to JSON. In the response header the content-type should be set to application/json to make sure that if we send a response encoded as JSON, it will be interpreted as JSON by the client as well.

Use ISO 8601 format for passing in and out dates and times. Use [UTC] as timezone.

Use language codes defined by the ISO 639 code standard.

Use country codes defined by the ISO 3166-1-alpha-2 code standard.

Use 3-character ISO-4217 codes for specifying currencies.

Whenever an API defines a property of type number or integer, the precision must be defined by the format as follows:

Good

Bad

URL parameters are the easiest way to add basic filtering to REST APIs. For example:

URL parameters only have a key and a value but filters are composed of three components.

One way to encode operators is the use of square brackets [] on the key name. For example:

Similar to the bracket approach:

If you require search on your endpoint, you can add support for filters and ranges directly with the search parameter

Field Selection (to avoid over-fetching)

Mobile clients display just a few attributes in a list. They don’t need all attributes of a resource. Give the API consumer the ability to choose returned fields. This will also reduce the network traffic and speed up the usage of the API.

Inclusion (to avoid under-fetching)

An example request without including associated resources:

An example request that includes an associated resource:

An example request that includes an associated resource selecting only some fields:

An example request that includes multiple associated resources selecting only some fields:

Allows ascending (+) and descending (-) sorting over multiple fields.

Lists that potentially larger than just a few hundred entries must support pagination to protect the service against overload as well as for best client side iteration and batch processing experience.

There are two popular techniques to support pagination:

To navigate to a specific page, next/prev page links were recommended to enhance the user experience. This favors cursor-based over offset-based pagination.

Choosing the right pagination technique depends on the particular use cases:

The cursor used for pagination is an opaque pointer to a page, that must never be inspected or constructed by clients. It usually encodes (encrypts) the page position, i.e. the identifier of the first or last page element, the pagination direction, and the applied query filters - or a hash over these - to safely recreate the collection. The cursor may be defined as follows:

The page information for cursor-based pagination should consist of a cursor set, that besides next may provide support for prev, first, last, and self as follows:

Define all success and service specific error responses in your API specification. Both are part of the interface definition and provide important information for service clients to handle standard as well as exceptional situations. But notice, it is not useful to document all technical errors, especially if they are not under control of the service provider. See overview on all HTTP status codes on Wikipedia

Success codes

For example, a 204 status code is commonly used with document editing interfaces corresponding to a "save" action, such that the document being saved remains available to the user for editing.

Redirection codes

Client side error codes

Server side error codes

Only returning status codes is usually not enough information to handle an error. High quality error codes tell you what went wrong and why it went wrong.

Three basic information should be included in every error message.

Let’s take the 400 - Bad request example: completely meaningless for the client-side resolution of the problem. The following example is much more precise:

The following example shows an error-message caused by a correct client side request. The parameter was transmitted correctly by the client but cannot be processed on the server side.

It’s not helpful to use the same structure for every error-cases. Some error-codes need more, some need less information. With regard to the API design it’s important to identify possible errors at the API and link them to the particular error codes. Furthermore, consider the error responses. Which parameters are returned in the response for which error case? The goal is to have one error code with defined response parameters for each potential error case. To identify the particular response parameter, a few questions should be clarified in advance:

The goal of caching is never having to generate the same response twice. Furthermore, by doing this, we gain speed and reduce server load. The best way to cache your API is to put a gateway cache (or reverse proxy) in front of it. A very powerful open-source reverse proxy is Varnish.

When a safe method is used on a resource URL, the reverse proxy should cache the response that is returned from your API, and then will use this cached response for all subsequent requests for the same resource before they hit your API.

When an unsafe method is used on a resource URL, the cache ignores it and passes it to the API.

Generally we assume that GET requests are cached and PUT, POST and DELETE requests are not. Unfortunately most APIs require additional caching rules for some requests. For these reasons, it’s a good idea to set cache-control headers. These contain many different options for the appropriate handling of cached data. Refer to Overview of Cache-Control HTTP headers for additional controls.

For example use max-age to indicate after how many seconds the response should be considered out-of-date:

To disable caching completely use the no-cache and no-store directives:

Compress the payload of your APIs responses using gzip, this helps to transport data faster over the network (fewer bytes) and makes frontends respond faster. But do not use gzip compression if you are serving so many requests that the time to compress becomes a bottleneck.

Next to requesting a particular resource, the client sends Accept-Encoding header that says what kind of compression algorithms the client understands. For example:

If the server understands one of the compression algorithms from Accept-Encoding, it can use that algorithm to compress the representation before serving it. When successfully compressed, server lets know the client of encoding scheme by the Content-Encoding header. For example:

If an API operation is asynchronous you must return a 202-ACCEPTED response code. This informs the client that the request has been accepted and understood by the server, but the resource is not yet completed. Instead of the URI of the actual resource, it would send a location to a status resource. For example a response like:

The location URI points to a (created) resource that will display the status of the asynchronous processing:

Request:

Response:

As soon as processing is done, the server can create the original resource and delete the queue-resource. If the client wants to fetch the status again, the server will return a 303-SEE OTHER code:

Request:

Response:

Every API description (contract) using HTTP(S) protocol MUST be tested against its API implementation. The tests can be executed using the Dredd testing framework.

In addition to local runs, the tests should be an integral part the API implementation’s CI/CD pipeline. The CI/CD pipeline should be configured to run the test whenever there is a change to either API description (contract) or its implementation.

GraphQL is an alternative to the REST-API allowing clients to query the data in the structure they need, rather than relying on a predefined data structure of a fixed API. This helps to avoid over- and underfetching but brings its own implementation challenges.

In conclusion GraphQL is an interesting approach, but does not offer a solution for all problems. It depends on the specific use case, which tool is more suitable.

OData (Open Data Protocol) is a HTTP based protocol which enables creation of REST-based services which allow resources identified using Uniform Resource Locators (URLs) and defined in a data model, to be published and edited by Web clients using simple HTTP messages.

OData is an alternative interface technology which fully supports the REST principles. It helps applications to focus on business logic without worrying about the various API approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats, query options, etc (For further reading: OData).

Often the architectural style of REST APIs is limited to CRUD operations only. Resources are often mapped exactly to the internal domain-/entity-types using the HTTP verbs (POST, GET, PUT, DELETE). But sometimes you have to implement some kind of business logic that is not directly related to a CRUD operation.

For example, you might want to block or suspend a user, which is different from deleting them. It is often possible to map these to update actions, for example, updating a user with a status attribute set to suspended but in some cases, this could feel clunky and forced.

In those cases, it makes sense to include actions as resources and place them at URLs such as:

It’s a great idea to denote them clearly, e.g., by prefixing them with /actions, although the use of a verb (like “suspend”) already gives it away that we’re breaking away from pure CRUD for better developer experience.

A standard way to check for existence is to use a HEAD request. The result of the HEAD request is either 200 OK if the resource exists or 404 NOT_FOUND if it does not. However, the usage of 4xx status codes implies an error situation. This might result in unintended triggering of error interceptors on the client side. And generally it is a bad practice to abuse exception handling for control flow.

So, what if non-existence is a valid result and not an error? For example checking the existence of the username before trying to create a user?

Bad

This is bad, because…​
…​ the type of response and status code is inconsistent with the ordinary GET request
…​ the username is used as a path parameter (see section Identification of Resources)

This is bad, because it introduces a new concept not compatible with REST principles (verb in the path).

Use filtering and selection for existence checks instead:

Good