API Versioning

Table of Contents

• General
• Scheme
• URL
• Backwards compatibility
• Forwards compatibility
  • Postel's Law
• Supporting old versions
• Deprecation and Sunsetting

---

General

Each of Qilin.Cloud APIs is working with a versioning system. These versions are independent from each other, with means the Qilin.Cloud uses different version for the single APIs. The version is included in the URL path and required in all API URLs.

After a API version is released, there is no more change on it. Every change leads into a new version, which can lead into a high frequency of versions.

Scheme

Qilin.Cloud API uses semantic versioning, but only the major, minor and patch version. Breaking changes are only introduced in new major versions.

Our versioning scheme:

v<major>.<minor>.<patch>

Example:

v1.0.1

where:

• major is used for a breaking change,
• minor is used for some addet functionality - non breaking,
• patch is used for some bugfixing - non breaking.

💡 Each segmnet can consist of up to 4 numbers, so the maximum version is v9999.9999.9999.

URL

You will find all information how to create the API URL on this wiki page: API URL.

This is the scheme for all Qilin.Cloud API endpoints:

https://<stage?>api.qilin.cloud/<apiName>/<version>/<endpoint>

Example:

https://api.qilin.cloud/products/v1.0.1/brand

Backwards compatibility

Changes on minor-version or patch-version are backwards compatibel. That means a program written against one version of that API will continue to work the same way, without modification, against future versions of the API. Only changes on major versions have NO backwards compatibility.

Forwards compatibility

An API is Forwards Compatible if a program written against one version of the API will also work the same way, without modification, against previous versions of the API.

We make no guarantee of Forwards Compatibility in Qilin.Cloud APIs, but we provide the following non-normative guidelines about our approach to forwards compatibility.

Postel's Law

🗣️ Be conservative in what you do, be liberal in what you accept from others

Where possible, we follow the Robustness Principle above. This means that the API will determine what to do with a request based only on the parts of that it recognises.

• Request query parameters that are not recognised by the server will be ignored.
• Expansion parameters that are not recognised by the server will be ignored.
• Properties of structured (i.e. JSON) data submitted via mutative requests that are not recognised by the server will be ignored.
• Data that is intended to be passed to any kind of extension that is not installed or is not active will be ignored.

Supporting old versions

All Qilin.Cloud APIs continues to support old versions of an API for 6 months from the time of public announcement for the new version of a given API. It is recommanded to check regularly. This can be be automated by checking HTTP headers for the attribute sunset-Header, which indicates when versions go offline.

Deprecation and Sunsetting

When talking about versioning in APIs, we should always have a look also about how Qilin.Cloud is anouncing a new version. Please read carefully this wiki page: API Lifecycle Management