Insights Hub API Lifecycle¶
Insights Hub web service APIs follow a defined lifecycle. This ensures API stability for clients in one phase while also enabling the introduction of new features into existing APIs in another phase.
Info
Use only APIs that have documented features. If any functionality is not explicitly specified, it can be changed without prior notice at any time.
Major Versions of Lifecycle Phases¶
The following diagram illustrates the two main phases of an API with a given major version:
After publication, an API of a given major version is deployed in the Insights Hub production environment for client use until its retirement. During the production phase of an API major version, only backward compatible updates (i.e., minor changes), bug fixes and security fixes are applied. Once an API major version is deprecated, no new features are introduced. Only security fixes and a select set of relevant bug fixes are implemented.
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 a certain period to allow clients to switch to the newer API major version.
Deprecation of API Entities¶
Deprecation serves as a hint to client developers that certain parts of an API or its versions will be retired in the future.
Important Note
Deprecation must not remove or break any existing API features. Deprecated major API versions should not receive updates with new features or bug fixes, but must receive security fixes.
Indication of API deprecation¶
If an entire API major version or part of an API is deprecated, this must be indicated in the API specification and documentation. When API entities are deprecated, this is indicated either through the deprecated
property in the OpenAPI Specification or with an appropriate description, like deprecated APIs. These deprecated entities can still be used, but they will be removed in the next major update of the API.
Deprecated APIs are removed from their services after giving users a 12-month notice for the major API versions and a 6-month notice for the minor API versions to manage their API services. This notice (12/6 month) starts once the deprecation announcement 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.