Skip to content

Insights Hub API Versioning

Each Insights Hub web service API is associated with a version value. API versioning is based on semantic versioning. In semantic versioning, an API version is identified with a specific version of three values: major, minor and patch. These values are typically formatted as MAJOR.MINOR.PATCH.

api

Major Version

A major version update indicates that breaking changes are made to an API. This indicates to users that there will be significant changes to the API that are required to upgrade to the new version. The major version of an API is part of the URL path of the Industrial IoT Gateway for calling a service API. For more information, refer to the Gateway Concepts.

A change is considered breaking if the behavior of an existing documented API feature is changed in such a way that clients using that feature may no longer function correctly. To work with the updated version, clients need to be modified. Examples of breaking changes include:

  • Removing, renaming or moving API entities, such as:
    • Endpoints
    • HTTP methods associated with endpoints
    • Operation query, body or header parameters
    • Schema properties
    • Authorization roles
  • Changing the way existing features need to be used, such as introducing new preconditions
  • Changing an already present workflow
  • Making optional parameters or schema properties mandatory
  • Changing documented functional or non-functional behavior in significant ways.

A major version update resets the minor and patch version values to zero. For example, if an API with version v3.1.2 undergoes a major update, the version changes to v4.0.0.

Minor Version

A minor update indicates backward-compatible changes in an API. Clients that are compatible with the minor update rules will continue to work with the updated API version.

A change is considered backward compatible if optional new features are added to an API. For example, adding optional API entities such as the ones mentioned above in breaking changes. A client is considered compatible with the minor update rules if it can handle new API entities, such as new optional schema properties or new error responses.

A minor version update resets the patch version values to zero. For example, if an API with version v3.1.2 undergoes a minor update, the version changes to v3.2.0.

Patch Version

A patch version update only relates to the API specification document. The implementation remains unchanged. Patch updates are corrections or improvements to descriptions or examples in the API specification. Patch updates might also fix a mismatch between specification and actual implementation of an API. This latter aspect is especially important for client developers who aim to develop compatible clients.

Last update: August 1, 2024

Except where otherwise noted, content on this site is licensed under the Development License Agreement.