Insights Hub API Lifecycle¶
Insights Hub web service APIs follow a defined lifecycle. This lifecycle guarantees API stability to clients on the one hand, and allows introducing new features into existing APIs on the other hand.
Info
We strongly recommend to only use documented features of APIs. Any functionality that is not explicitly specified can be changed without prior notice at any time.
Major Version Lifecycle Phases¶
The following diagram shows the two main phases of an API with given major version:
After publication and before retirement, an API of given major version is deployed in a Insights Hub production environment to be used by clients. During production phase of an API major version, backwards compatible updates (i.e., minor changes), bug fixes and security fixes are applied to the API. Once an API major version gets deprecated, no new features are added. Only security fixes are applied and a subset of relevant bug fixes.
Major Version Update¶
A major API version is deprecated once a newer major version of the API is published. The old major version is still available for some time to allow clients to switch to the newer API major version.
Deprecation of API Entities¶
Deprecation is a hint to client developers that parts of an API or its versions are to be retired in the future.
Deprecation MUST NOT remove or break any existing API features. Deprecated major API versions SHOULD NOT obtain updates with new features or bug fixes and MUST obtain updates with security fixes.
Indication of API 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. If API entities are deprecated, this is indicated either using the deprecated property in the OpenAPI Specification or by a proper description. Just like deprecated APIs, they can still be used. Deprecated API entities will be removed in the next major update of the API.
The deprecated APIs are removed from its services giving the users a duration of 12 months for the major API version and 6 months for the minor API version to manage their API services. This 12/6 months of duration starts once the announcement of the deprecation is made via Release notes and the notification center in the Launchpad.
Related Links¶
Except where otherwise noted, content on this site is licensed under the Development License Agreement.