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 Versioning Guidelines

Note

The versioning guidelines are published under common guidelines and this document, so that you can refer to them and not lose the context for versioning in REST guidelines. The content of the versioning guidelines is the same in both places.

Introduction

API Versioning provides a mechanism to support backward compatibility or multiple versions of an API running in parallel. It helps in effectively managing the API changes and its impact on API clients. API versioning provides a mechanism to maintain traceability of changes during the evolution of an API.

The intention of having more than one version of an API is to provide the ability to strategically evolve an API over time while being able to control the scope of impact during migration phases. It is neither a way of having each version for different functionality, nor a version for each use case or process.

API versioning is based on the Semantic Versioning 2.0.0 | Semantic Versioning.

API Version Numbering

Semantic versioning MUST be used to version individual APIs, based on the Semantic Versioning 2.0.0 | Semantic Versioning. Please find below some examples (for major, minor and patch changes) of semantic versioning.

A version number MUST be expressed as a tuple of three version values separated by dots "." as

<MAJOR>.<MINOR>.<PATCH>
example 1.0.4

Each version value MUST be a non-negative integer consisting of digits only, without trailing zeros.

Released APIs MUST increment their

<MAJOR> version, when incompatible changes are made

<MINOR> version, when functionality is added or behavior is improved in a backward compatible way

<PATCH> version, when backward compatible/transparent implementation changes are made

Major version change (non-backward compatible resource change)

A major version change is one that impacts existing API clients.

The following are some examples of major version changes.

  • A change in the name or data type of a resource, parameter, request or response property
  • A change in the format of a request or response
  • Addition of a new mandatory field or making an optional field mandatory in request
  • Removal of a resource, operation, or a field

Minor version change (backward compatible change)

A minor version change is one that adds new functionality while having zero impact on existing API clients.

The following are some examples of minor version changes.

  • Addition of a new operation had no impact on the utilization of the existing operations
  • Addition of new, optional to use, request parameter(s) such as query parameter(s) or header(s) in the existing operation(s)
  • Addition of new, optional to send, request body properties in the existing operation(s)
  • Addition of new response body properties or header(s) in the existing operation(s), that are not required to be used in order to realize any existing functionality

Patch version change (Backward Compatible Change)

A Patch version occurs whenever there are changes that do not add new functionality.

Pre-release version

Pre-release versions are indicated using the pre-release as described in Semantic Versioning 2.0.0 | Semantic Versioning.

Pre-release versions MAY be used for APIs released to a specific API client for evaluation before they are released as generally available. These are also called "Early Access" in the API lifecycle. They can be incomplete but SHOULD be of production quality.

Pre-release versions might not satisfy the intended compatibility requirements as denoted by its associated normal version.

An additional indication is appended after the patch indication with this format: <MAJOR>.<MINOR>.<PATCH>-<pre-release>

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes.

Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.

API version in HTTP requests [200]

API clients MUST be able to choose a major API version if multiple major API versions are available. This should apply regardless of the option chosen for the express version.

API SHOULD implement one of the two options below.

Optionally, API pre-releases can be implemented according to the descriptions of semantic versioning in the Pre-release version section.

Option 1 - API version in URI path [200.1]

The Major version number MUST be specified in the URI as a path segment.

example: https://example.com/myapi/v1/<resource-name>

Where v1 represents Major version 1, the latest minor version and the latest patch version in that minor version.

Option 2 - API version in custom request header [200.2]

A request HTTP header e.g., Api-Version MUST be supported to allow API clients to specify the version.

The header has the form Api-Version: <MAJOR>.

If an API implementation allows calling it without version and when no version is specified, the latest API version compatible to first release SHOULD be used. Based on business requirements, the API implementation could also choose another strategy (which should be documented), for example to return the latest version or a dedicated specific version.

API Version in HTTP Responses [201]

A header with full semantic version value SHOULD be returned in the response e.g., Api-Version: <MAJOR>.<MINOR>.<PATCH>.

Contact us