Skip to main content

Documentation and API Descriptions

Use of OpenAPI/Swagger for API Documentation​

The documentation of all APIs published through our API Gateway must (MUST) be created using the OpenAPI Specification (OAS). We support both version 2.0 and 3.0.x of the specification to ensure flexibility and adherence to current standards.

  • Version 2.0 (SHOULD): Teams should use this version when building upon existing projects or when specific tools and integration environments require it.
  • Version 3.0.x (MUST): For all new projects and major overhauls of existing APIs, the use of OAS 3.0.x is mandatory (MUST). This version offers enhanced features, such as improved support for callbacks, links, and the representation of more complex security schemes.

Elements of Documentation​

  • General API Information (MUST): Every API documentation must (MUST) include clear information about the purpose of the API, the author, version, and any relevant contact details.
  • Endpoints and Operations (MUST): The documentation must (MUST) provide detailed descriptions of all endpoints, including the supported HTTP methods, possible responses, error codes, and parameters and values.
  • Examples and Use Cases (SHOULD): To facilitate understanding and practical application of the API, the documentation should (SHOULD) include practical examples and common use cases.
  • Error Codes and Messages (MUST): A complete list of all possible error codes with corresponding explanations and remediation strategies is mandatory (MUST).