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.

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:

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 communicated, which means that it 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.

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.