The titles are marked with the corresponding labels: {MUST}, {SHOULD}, {MAY}.
We use the OpenAPI specification (aka Swagger spec) as standard for our REST API definitions. You have to provide the API definition in YAML format (instead of JSON) for the OpenAPI API definition files due to its improved readability.
Please stick to version 2.0 of the specification for now, until we succeed to update all our tooling to support the upcoming version 3.0.
We also call the OpenAPI API definition the "API Reference definition" (or "API definition"); as a reference manual it provides all information needed by an experienced API client developer to use this API.
The OpenAPI API specification file should be subject of version control together with source code management. Services also have to support an endpoint to access the API Reference definition for their external API(s).
In addition to the API as OpenAPI Reference Definition, it’s good practice to provide an API User Manual documentation 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:
-
API’s scope, purpose and use cases
-
concrete examples of API usage
-
edge cases, error situation details and repair hints
-
architecture context and major dependencies - including figures and sequence flows
The User Manual must be posted online, e.g. via GitHub Enterprise pages, on specific team web servers, or as a Google doc. And don’t forget to include a link to this user manual into your OpenAPI definition using the “externalDocs” property.