REST-API Design Rules (Nederlandse API Strategie IIa) 1.0

API-05: Use nouns to name resources

Because resources describe things (and thus not actions), resources are referred to using nouns (instead of verbs) that are relevant from the perspective of the user of the API.

API-54: Use plural nouns to name collection resources

Because a collection resource represents multiple things, the path segment describing the name of the collection resource must be written in the plural form.

https://api.example.org/v1/gebouwen
https://api.example.org/v1/vergunningen

Singular resources contained within a collection resource are generally named by appending a path segment for the identification of each individual resource.

https://api.example.org/v1/gebouwen/3b9710c4-6614-467a-ab82-36822cf48db1
https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f

Singular resources that stand on their own, i.e. which are not contained within a collection resource, must be named with a path segment that is written in the singular form.

https://api.example.org/v1/gebruikersprofiel

API-04: Define interfaces in Dutch unless there is an official English glossary available

Since the exact meaning of concepts is often lost in translation, resources and the underlying attributes should be defined in the Dutch language unless there is an official English glossary available. Publishing an API for an international audience might also be a reason to define interfaces in English.

Note that glossaries exist that define useful sets of attributes which should preferably be reused. Examples can be found at schema.org.

API-48: Leave off trailing slashes from URIs

According to the URI specification [rfc3986], URIs may contain a trailing slash. However, for REST APIs this is considered as a bad practice since a URI including or excluding a trailing slash might be interpreted as different resources (which is strictly speaking the correct interpretation).

To avoid confusion and ambiguity, a URI must never contain a trailing slash. When requesting a resource including a trailing slash, this must result in a 404 (not found) error response and not a redirect. This enforces API consumers to use the correct URI.

https://api.example.org/v1/gebouwen

https://api.example.org/v1/gebouwen/

API-53: Hide irrelevant implementation details

An API should not expose implementation details of the underlying application. The primary motivation behind this design rule is that an API design must focus on usability for the client, regardless of the implementation details under the hood. The API, application and infrastructure need to be able to evolve independently to ease the task of maintaining backwards compatibility for APIs during an agile development process.

A few examples of implementation details:

• The API design should not necessarily be a 1-on-1 mapping of the underlying domain- or persistence model
• The API should not expose information about the technical components being used, such as development platforms/frameworks or database systems
• The API should offer client-friendly attribute names and values, while persisted data may contain abbreviated terms or serializations which might be cumbersome for consumption

API-03: Only apply standard HTTP methods

The HTTP specification [rfc7231] and the later introduced PATCH method specification [rfc5789] offer a set of standard methods, where every method is designed with explicit semantics. Adhering to the HTTP specification is crucial, since HTTP clients and middleware applications rely on standardized characteristics. Therefore, resources must be retrieved or manipulated using standard HTTP methods.

The following table shows some examples of the use of standard HTTP methods:

API-01: Adhere to HTTP safety and idempotency semantics for operations

The HTTP protocol [rfc7231] specifies whether an HTTP method should be considered safe and/or idempotent. These characteristics are important for clients and middleware applications, because they should be taken into account when implementing caching and fault tolerance strategies.

Request methods are considered safe if their defined semantics are essentially read-only; i.e., the client does not request, and does not expect, any state change on the origin server as a result of applying a safe method to a target resource. A request method is considered idempotent if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request.

The following table describes which HTTP methods must behave as safe and/or idempotent:

API-02: Do not maintain session state on the server

In the context of REST APIs, the server must not maintain or require any notion of the functionality of the client application and the corresponding end user interactions. To achieve full decoupling between client and server, and to benefit from the advantages mentioned above, no session state must reside on the server. Session state must therefore reside entirely on the client.

API-06: Use nested URIs for child resources

When having a child resource which can only exist in the context of a parent resource, the URI should be nested. In that case, the child resource does not necessarily have a top-level collection resource. The best way to explain this design rule is by example.

https://api.example.org/v1/articles/123/comments

https://api.example.org/v1/photos/456/comments

https://api.example.org/v1/comments

https://api.example.org/v1/comments/123
https://api.example.org/v1/comments/456

API-10: Model resource operations as a sub-resource or dedicated resource

There are resource operations which might not seem to fit well in the CRUD interaction model. For example, approving of a submission or notifying a customer. Depending on the type of the operation, there are three possible approaches:

1. Re-model the resource to incorporate extra fields supporting the particular operation. For example, an approval operation can be modelled in a boolean attribute goedgekeurd that can be modified by issuing a PATCH request against the resource. Drawback of this approach is that the resource does not contain any metadata about the operation (when and by whom was the approval given? Was the submission declined in an earlier stage?). Furthermore, this requires a fine-grained authorization model, since approval might require a specific role.
2. Treat the operation as a sub-resource. For example, model a sub-collection resource /inzendingen/12/beoordelingen and add an approval or declination by issuing a POST request. To be able to retrieve the review history (and to consistently adhere to the REST principles), also support the GET method for this resource. The /inzendingen/12 resource might still provide a goedgekeurd boolean attribute (same as approach 1) which gets automatically updated on the background after adding a review. This attribute should however be read-only.
3. In exceptional cases, the approaches above still don't offer an appropriate solution. An example of such an operation is a global search across multiple resources. In this case, the creation of a dedicated resource, possibly nested under an existing resource, is the most obvious solution. Use the imperative mood of a verb, maybe even prefix it with a underscore to distinguish these resources from regular resources. For example: /search or /_search. Depending on the operation characteristics, GET and/or POST method may be supported for such a resource.

In this design rule, approach 2 and 3 are preferred.

API-16: Use OpenAPI Specification for documentation

The OpenAPI Specification (OAS) [OPENAPIS] defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

API documentation must be provided in the form of an OpenAPI definition document which conforms to the OpenAPI Specification (from v3 onwards). As a result, a variety of tools can be used to render the documentation (e.g. Swagger UI or ReDoc) or automate tasks such as testing or code generation. The OAS document should provide clear descriptions and examples.

API-17: Publish documentation in Dutch unless there is existing documentation in English

In line with design rule API-04, the OAS document (e.g. descriptions and examples) should be written in Dutch. If relevant, you may refer to existing documentation written in English.

API-51: Publish OAS document at a standard location in JSON-format

To make the OAS document easy to find and to facilitate self-discovering clients, there should be one standard location where the OAS document is available for download. Clients (such as Swagger UI or ReDoc) must be able to retrieve the document without having to authenticate. Furthermore, the CORS policy for this URI must allow external domains to read the documentation from a browser environment.

The standard location for the OAS document is a URI called openapi.json or openapi.yaml within the base path of the API. This can be convenient, because OAS document updates can easily become part of the CI/CD process.

At least the JSON format must be supported. When having multiple (major) versions of an API, every API should provide its own OAS document(s).

https://api.example.org/v1/openapi.json

https://api.example.org/v1/openapi.yaml

API-56: Adhere to the Semantic Versioning model when releasing API changes

Version numbering must follow the Semantic Versioning [SemVer] model to prevent breaking changes when releasing new API versions. Versions are formatted using the major.minor.patch template. When releasing a new version which contains backwards-incompatible changes, a new major version must be released. Minor and patch releases may only contain backwards compatible changes (e.g. the addition of an endpoint or an optional attribute).

API-20: Include the major version number in the URI

The URI of an API (base path) must include the major version number, prefixed by the letter v. This allows the exploration of multiple versions of an API in the browser. The minor and patch version numbers are not part of the URI and may not have any impact on existing client implementations.

API-57: Return the full version number in a response header

Since the URI only contains the major version, it's useful to provide the full version number in the response headers for every API call. This information could then be used for logging, debugging or auditing purposes. In cases where an intermediate networking component returns an error response (e.g. a reverse proxy enforcing access policies), the version number may be omitted.

The version number must be returned in an HTTP response header named API-Version (case-insensitive) and should not be prefixed.

API-Version: 1.0.2

API-55: Publish a changelog for API changes between versions

When releasing new (major, minor or patch) versions, all API changes must be documented properly in a publicly available changelog.

API-18: Include a deprecation schedule when deprecating features or versions

Managing change is important. In general, well documented and timely communicated deprecation schedules are the most important for API users. When deprecating features or versions, a deprecation schedule must be published. This document should be published on a public web page. Furthermore, active clients should be informed by e-mail once the schedule has been updated or when versions have reached end-of-life.

API-19: Schedule a fixed transition period for a new major API version

When releasing a new major API version, the old version must remain available for a limited and fixed deprecation period. Offering a deprecation period allows clients to carefully plan and execute the migration from the old to the new API version, as long as they do this prior to the end of the deprecation period. A maximum of 2 major API versions may be published concurrently.