API governance
Qlik takes the relationship with partners and customers seriously. This also relates to the APIs offered. Sometimes, to introduce new features, or to keep APIs simple to use, there may be times where changes to the APIs are needed and that's where Qlik's API governance policy comes in. It ensures that API changes are done in a sensible manner for both you as an end-user of them, and also for the API maintainers themselves.
The policy consists of five parts, each having its own section below.
Versioning
The versioning policy is a simple set of rules and requirements for an API, that dictate how the version numbers should be assigned and incremented.
It follows industry standard semantic versioning. A version
number must take the form X.Y.Z, where X is the major version, Y is the
minor version, and Z is the patch version.
The advantage of using this method of versioning is that by comparing two versions, you can determine the compatibility differences.
| Version change | Compatibility difference |
|---|---|
| Z is incremented | Backwards-compatible bug fixes |
| Y is incremented | New backwards-compatible features |
| X is incremented | Backwards-incompatible changes |
Major version zero, 0.Y.Z, is for initial development, and isn't covered
by this policy.
Visibility index
The visibility index defines who is the intended user of the API. There are two types of APIs: private and public.
Public APIs are officially supported, and therefore also officially documented. To avoid the risk that your solution might break with any new product version, you should always use public APIs.
Stability index
The stability index indicates how stable or mature an API is. There are three levels:
| Stability index | Description |
|---|---|
| Experimental | This API is under development. Don't rely on it. It may change or be removed in future versions. |
| Stable | Stable APIs are reliable and breaking changes are unlikely. |
| Locked | Locked APIs are extremely reliable and shouldn't be broken unless absolutely necessary. |
Deprecation policy
The deprecation policy defines when and how an API is considered to be deprecated.
The goal is always to minimize changes to APIs, but it's sometimes necessary due to architectural changes and with the introduction of new capabilities.
The deprecation period starts when the deprecation has been officially communicated. A replacement must be announced at the same time as the deprecation period starts unless the API is to be sunset. This gives you a period in which you can start adapting your custom solution to the API replacement and prepare for the API change.
The deprecation period varies depending on the maturity of the API, which is based on its stability index. The deprecation period lasts until the removal has been officially communicated.
| Stability index | Deprecation period |
|---|---|
| Experimental | No deprecation period |
| Stable | Deprecation period of 6 months |
| Locked | Deprecation period of 12 months |
Breaking change definition
The breaking change definition is a set of rules that defines if a change is considered to be a backward or non-backward compatible change. These rules vary depending on API type.
