With these guidelines, we aim to establish a set of best practices and standards for designing, developing, documenting, and maintaining APIs.

Skip to:

• Purpose
• How to read the guidelines
• API linting
  • Installation
  • Recommended Redocly configuration
  • Lint your specs
  • Change severity
• Attribution

We consider API guidelines essential to ensure that our APIs are consistent, reliable, secure, and easy to use.

Our APIs are a valuable part of our business assets, as with APIs we generate the corresponding operating values. Ideally, by applying the API guidelines, all APIs look as if they were created by a single team, thus providing API consumers with a homogeneous, easy-to-use product. This facilitates a great developer experience and the ability to quickly compose complex business processes. With this in mind, we trust that our teams build APIs that are:

• self-explanatory
• easy to use and robust
• of high quality
• consistent
• transparently versioned
• RESTful with respect to REST APIs.

These guidelines include rules for REST and asynchronous APIs and are supplemented by rules applicable to both types of APIs. It is a living document and will be revised over time as new rules are added or existing rules are modified.

The guidelines are structured into individual rules that use the key words “MUST”, “MUST NOT”, “SHOULD”, “SHOULD NOT”, and “MAY”. These keywords are to be interpreted as described in RFC2119. In this document, such keywords are highlighted at the beginning of each section in uppercase letters and are color-coded.

Disclaimer: Code examples may be incomplete and/or may violate the rules described in the guidelines. Examples are intentionally kept simple to make them more accessible and easier to comprehend. They are always correct in their context, but not necessarily outside of it. Common examples for this are omitted headers such as Authorization or omitted (mandatory) properties in JSON responses.

Our APIs can be validated using the Redocly CLI toolbox. By automating the verification of APIs againgst our guidelines, we enable our developers to get a much quicker view of where API design needs to be adjusted. If you'd like to use it for your own APIs, this is what you need to do:

1. Install Redocly CLI.

2. Add the following code snippet to your existing .npmrc or create a .npmrc. Set a valid GITHUB_TOKEN. (Sadly this necessary even if packages are public, we hope publishing packages to https://www.npmjs.com later to avoid this step)

   @otto-de:registry=https://npm.pkg.github.com/
   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
   

3. Install the dependency.

   npm install -D @otto-de/api-guidelines

4. Add the following code snippet to your redocly configuration:

   extends:
     - api-guidelines/recommended
   
   plugins:
     - ./node_modules/@otto-de/api-guidelines/dist/plugin.cjs

extends:
  - recommended
  - api-guidelines/recommended

plugins:
  - ./node_modules/@otto-de/api-guidelines/dist/plugin.cjs

redocly lint ./path/to/your/spec.yml

If you'd like to disable or change the severity of a specific rule, you can add this to your Redocly configuration, for example, like this:

rules:
  api-guidelines/always-return-json-object: off
  api-guidelines/define-permissions-with-scope: warn

At this point we would like to send Kudos to Zalando SE whose Tech Team did a great job crafting the Zalando RESTful API Guidelines. As much of the content resonates with what we do at OTTO, their well-prepared document inspired us and in certain parts provided a basis when crafting the OTTO API Guidelines.

The Zalando RESTful API Guidelines are published under the Creative Commons Attribution 4.0 International License (CC BY 4.0). For further notes on these OTTO API Guidelines’ license under CC BY 4.0, please refer to the Creative Commons Attribution 4.0 International Public License.