The titles are marked with the corresponding labels: {MUST}, {SHOULD}, {MAY}.
You must design your APIs consistently with these guidelines; use our API linter for automated rule checks, but not every rule can be automated.
You should follow the API First Principle, more specifically:
-
You should define APIs first, before coding their implementation, using OpenAPI as the specification language
-
You should call for early review feedback from peers and client developers
We use the OpenAPI specification as the standard to define API specification files. OpenAPI 3.0 must be supported, but you MAY support other versions, like Swagger 2.
The API specification files should be subject to version control using a source code management system.
You must publish the component API specification with the deployment of the implementing service, and, hence, make it discoverable for the appropriate group via our API Portal.
Within the API specification, you must provide sufficient information in the description of the API to facilitate proper usage. This may include:
-
API scope, purpose, and use cases
-
Major edge cases
-
Major dependencies
In addition to the API Specification, it is good practice to provide a separate API user manual to improve client developer experience, especially of engineers that are less experienced in using this API. A helpful API user manual typically describes the following API aspects:
-
concrete examples of API usage
-
edge cases, error situation details, and repair hints
-
architecture context and dependencies - including figures and sequence flows
The user manual must be published online, e.g. via our documentation hosting platform service. Please do not forget to include a link to the API user manual into the API specification using the #/externalDocs/url property.
|
Note
|
This manual does not have to be created by engineering, but could be created by a documentation team, Developer Relations or by community effort. It is important to provide extra documentation for our developers to reduce the number of support related questions that come in. |
Every query/path parameter and request/response property in the API specification must have a description
Every query/path parameter and request/response property in the API specification must have an accurate example. An accurate example will show the API consumer what an input/output value will realistically look like, and could even be used in a real request/response. However, take care to not use personally identifiable information or secrets in examples.
Every operation (POST, PUT, PATCH, etc) may define one or more operation level examples.
Certain tools, like Postman, have a limit on how many words can be displayed within the operation summary. It is helpful for consumers to have short summaries that describe the operation at its most basic level to improve readability for consumers.