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 Specification

APIs MUST come with API specifications as means of detailed technical documentation. For synchronous HTTP-based APIs, OpenAPI specifications of at least version 3 MUST be used. For asynchronous messaging APIs, AsyncAPI specifications of at least version 2 MUST be used. The API specifications SHOULD be provided in YAML format for consistency reasons.

Implementation aspects. An API specification represents a logical grouping of API entities such as synchronous HTTP operations or asynchronous messaging topics. Mapping of an API specification to one or more physical runtime services is up to the API provider and SHOULD not be visible to API users. Regardless of how API specifications are mapped to runtime services, implementations MUST always be in sync with the provided API specifications.

API specification content. API specifications MUST include or reference all syntactic information required for client developers. A minimum level of semantic information SHOULD be included to allow client developers with normal domain knowledge to understand the purpose and usage of the API. The following list shows REQUIRED content:

  • fully defined request and response, or message schemas
  • header, query, and path parameter details including allowed values and default values
  • details on error response status codes, error schemas, error types, and a clear association of errors to operations
  • restrictions with respect to format, character or number range of parameters and properties
  • restrictions with respect to number of array items or additional properties
  • examples for all parameters and request/response bodies
  • descriptions and summaries SHOULD contain meaningful additional information to already existing information such as the names of properties, parameters, or operations
  • limits which are dependent on the used service plan, acquired quota, the service region or deployment environment MAY be mentioned in the API specification, but their concrete values SHOULD NOT be added to an API specification (see service usage limits in API Documentation).
  • deprecation notes, see below

Deprecation notes. Deprecation notes MUST be added to an API specification according to Guideline Lifecycle Phases. OpenAPI or AsyncAPI properties description and deprecated SHOULD be used, if applicable. Deprecation notes SHOULD mention which other API or part of an API should be used instead of the deprecated one. For HTTP APIs, e.g., endpoints, methods, parameters, supported media types, parts of request or response body schemas, MAY be deprecated. For asynchronous messaging APIs, e.g., message topics, messages, or parts of message schemas MAY be deprecated.

Examples

External and internal APIs. A runtime service offers only part of its implemented API operations to project external users, but all operations to internal services. An external API specification is created to only contain the external API details. An internal API specification is created to contain only the internal API details. Both API specifications are offered to internal users, while external users only have access to the external API specification. Of course, suitable access control mechanisms should be in place to prevent unauthorized use of internal APIs by external users.

Web application backend APIs. A project uses a dedicated backend for project-provided web application frontends. The backend's API is internal, as only meant to be used by the project's web applications. Hence, the API specification is not published outside of the project. Technically, however, the backend API may be accessible by external users of the web applications.

Usage dependent limits. An API to manage assets comes with usage limits on the number of assets which can exist for one tenant. The API specification mentions that the number of assets is limited per tenant and refers to another page in the API documentation dedicated to describing usage limits. The API limit documentation page lists limits depending on API deployments (e.g., regions) and offered service plans.

Contact us