Skip to content

Insights Hub API Versioning

Each Insights Hub web service API is associated with a version value. API versioning in is based on semantic versioning. To identify a specific version of an API, three version values are used:

api

Major Version

A major version update indicates breaking changes in an API. The major version of an API is part of the URL path of Industrial IoT Gateway for calling a service API. Refer to Gateway Concepts for more information.

A change is considered as breaking, if the behavior of an existing documented API feature is changed in a way such that clients using that feature might not work anymore. To be able to work with the updated version, the clients need to be modified. Breaking changes are, e.g.:

  • 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 how existing features need to be used, e.g., by introducing new preconditions to be fulfilled
  • 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 initially. For example, in case an API with version v3.1.2 undergoes a major update, the version value is changed to v4.0.0.

Minor Version

A minor update indicates backwards 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 as backwards compatible, if optional new features are added to an API. For example, adding optional API entities such as the ones mentioned above for breaking changes. A client is considered compatible with the minor update rules if it tolerates new API entities, e.g., new optional schema properties or new error responses.

A minor version update resets the patch version values to zero. For example, in case an API with version v3.1.2 undergoes a minor update, the version value is changed 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 of descriptions or examples in the API specification. Patch updates might also fix a mismatch between specification and actual implementation of an API. The latter case is particularly important for client developers, who want to develop compatible clients.


Last update: July 6, 2023

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