The chat responses are generated using Generative AI technology for intuitive search and may not be entirely accurate. They are not intended as professional advice. For full details, including our use rights, privacy practices and potential export control restrictions, please refer to our Generative AI Service Terms of Use and Generative AI Service Privacy Information. As this is a test version, please let us know if something irritating comes up. Like you get recommended a chocolate fudge ice cream instead of an energy managing application. If that occurs, please use the feedback button in our contact form!

Provide Feedback

Feedback sent

Thank you for your feedback!

Provide Feedback

Please log in to provide feedback
Skip to content
Siemens Xcelerator Marketplace

API Documentation

APIs MUST come with a documentation that is structured according to (logical) services. Each service consists of a set of one or more APIs and additional service-specific documentation. Cross-cutting topics such as access control or versioning SHOULD be gathered in dedicated documentation pages which MUST be referenced in the individual service documentation pages.

The individual service documentation consists of the following parts:

Service introduction. Every service MUST provide an introduction, with information about the context of the service, its main domain entities, and major use cases.

API specifications. Every API major version offered by a service MUST come with an own API specification (see API Specification). If an API version is offered in multiple deployment regions or environments, the corresponding information MUST be provided. Visualizations for each API specification MUST be provided, e.g., in form of Swagger UI or generated AsyncAPI HTML pages. There MUST be a possibility for users to download the API specifications.

Access control. Every API MUST document (or link to) access control information relevant for its intended users. Permissions MUST be documented with clear association to API operations in the corresponding API specification or in separate documents, as appropriate.

Service usage limits. API usage limits describe how many resources of an API are available per user account or tenant. API resources may be REST resources, the number of requests or amount of data being transferred in given time windows, or limits for service-specific metrics. The service documentation SHOULD describe existing usage limits and provide limit values for static limits. Limits depending on acquired service plans or usage quota SHOULD only be mentioned, but described at the respective pages of service plans or quota. API parameter or body property format limits MUST be described in the API specification (see API Specification).

Service changelog. For every service, a changelog MUST be provided. The changelog includes timestamped summaries of changes and relates the changes to the respective API versions.

Service usage guide. Services SHOULD come with a usage guide, showing relevant workflows or interplays of offered API operations. A usage guide SHOULD NOT be a pure listing of request and response examples for individual operations, as this information is already provided in the API specifications.

Migration guides. In case a new major version of an API has been released, a migration guide SHOULD be provided for users of the old major version.

Cross-cutting API concerns. Topics which address multiple or all APIs MUST be described in documents outside the service individual documentation. Among those topics are the following:

  • Base URLs for how to reach APIs, if not fully described in API specifications
  • Common API security and access mechanisms
  • Common API error types
  • API versioning, backward compatibility, deprecation, and lifecycle

API cookbook recipes. Recipes for how to solve typical problems with the offered service APIs SHOULD be given. In contrast to the API usage guides, cookbook recipes have a larger scope and show how to integrate with existing tools or other solutions.

Contact us