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 Lifecycle Phases

Once an API with major version >= 1 is published and accessible to external customers or Siemens-internal developers, it MUST be offered in accordance with the following sequence of lifecycle phases:

  1. Early Access
  2. Production
  3. Deprecation
  4. Retirement

The lifecycle phases are in the context of ONE major API version. In case a new major version of the same API is published, it MUST follow its own lifecycle. The phases are described in more detail in the following subsections.

Early Access

The early access lifecycle phase is OPTIONAL to be used and is a means of obtaining additional feedback from customers. An early access API MAY be offered to a selected subset of customers or to all customers publicly. Early access is typically used for new major API versions, but MAY be used for new minor versions with significant additions, too.

An early access API MAY undergo any type of changes including breaking changes. However, early access APIs SHOULD be of production quality already and are no means for beta testing or similar.

Early access API versions MUST be indicated by the suffix -earlyaccess. See Guideline API Versioning for more details on how to version early access APIs.

To interact with an early access API, clients MUST explicitly request to interact with an early access version of the API. Switching from an early access version to a production version of an API MUST require an explicit change in the client request. See Guideline API Version in HTTP Request for details on how clients interact with early access versions using HTTP.

Early access versions SHOULD NOT be retired immediately when the production version of the API is published. Retiring an early access API version SHOULD be done only after careful evaluation of effects on customers. Customer data created by an early access API version MAY be migrated to the production version of the API. It SHOULD be communicated and documented for customers which strategy for early access version retirement and data migration is followed.

Examples

For a new API, an early access version is published to selected customers with version

v1-earlyaccess

An existing API of version 1.1.0 is extended with a new set of functionalities. The new set of functionalities is anticipated to be backward compatible and should be offered as early access publicly. Regardless of the anticipated backward compatibility, the early access version is published as

v2-earlyaccess

In case the changes can be realized in backward compatible manner, the early access version might end up as production version 1.2.0 or a later minor version 1.x.0. In case the changes need to be revised and turn out to be breaking, the early access version might end up as production version 2.0.0.

Production

The main phase for customers to use an API is its production phase. A production major API version MAY obtain features updates, security or bug fixes. All changes to the major API version MUST be backward compatible (see Guideline API Versioning).

Deprecation

Deprecation is a hint to client developers that parts of an API or a complete API major version are to be retired in the future.

Deprecation MUST NOT remove or break any existing API features.

A major API version SHOULD be deprecated when its successor major version is introduced or when an API is supposed to be retired without successor in the future. Deprecated major API versions SHOULD NOT obtain updates with new features or bug fixes and MUST obtain updates with security fixes.

Indication of deprecation. In case a complete API major version or part of an API is deprecated, this MUST be indicated in the API specification and documentation of the API.

Deprecation header. For HTTP APIs, a deprecation header SHOULD be added to responses using deprecated API versions or deprecated parts of an API version. The deprecation header MUST be of the form

Deprecation-Version: <VERSION>

where <VERSION> MUST be the full semantic version of the API at time of deprecation (see Guideline API Versioning). In addition to the Deprecation-Version header field, other header fields MAY be used to convey additional information related to deprecation, as indicated in draft-dalal-deprecation-header.

Examples

To avoid breaking changes, a REST resource asset is deprecated and a new resource assetV2 is introduced as minor update to an API. The API version introducing the deprecation and new resource is 1.8.0. The endpoints of resource asset are marked deprecated in version 1.8.0 and requests to asset endpoints return the following deprecation header

Deprecation-Version: 1.8.0

Retirement

API retirement means to remove a complete API major version from operation. Clients still using the API version will immediately stop working. API retirement may be highly undesirable from a customer's point of view and MUST be carefully evaluated according to domain and customer needs.

To make the retirement of an API possible, API usage SHOULD be monitored to identify remaining customers. To encourage API users to move to newer or alternative API versions, new API versions SHOULD be advertised, and existing users SHOULD get migration support.

Contact us