Date-based API versioning for CDF

Hi, my name is Geir Engdahl and I’m co-founder and CTO of Cognite. Cognite is currently considering a new mechanism for API versioning for the CDF API. What are your thoughts on this proposed mechanism? I am very eager to hear your input!

Why 

The goal of this mechanism is to:

• Make it easier to make smaller breaking (ie. non backwards-compatible) changes to the API

• Allow us to run multiple versions of the API in parallel

• Avoid unexpected breakages for API clients

• Make upgrading version as easy as possible for API clients

• Be backwards compatible so no existing clients break

An example of a breaking change could be to introduce a cleaner structure in the JSON request body for a particular query endpoint, e.g by replacing a previous string field with a nested JSON object.

How to 

Our preferred method of accomplishing this is with a new API header, cdf-version, which takes the format YYYYMMDD and fixes an API client to the API as of that date. We consider this version as a major version, meaning breaking changes can occur when you change this. API clients which do not specify this header will default to a fixed date before we introduce this mechanism, ensuring that they do not break.

We will publish updates to the API on a regular basis, and breaking changes will only become visible by setting the cdf-version header to a date greater or equal to the date the change was introduced. It will not be possible to request the “latest” version of the API, short of parsing the current date and dynamically updating the header, which would be extremely dangerous, since unexpected breaking changes could be introduced this way.

Each version of our SDKs will be pinned to a particular version of the API. Upgrading to a new SDK version will automatically upgrade to a newer API version. The versioning scheme of the SDKs will continue as today.

Why not just change the v1 in the API url to v2 and on? We will keep the v1 in the URL and increment that version if we make large structural changes to the API. This will most likely not happen in the near future, as it has proven to be a very heavyweight mechanism.

Limitations

One of the limitations is that the version header is shared between all endpoints of the API. So if you want a new feature under /timeseries which requires a date greater than X, you will also need to make sure that you support breaking changes up to this date under all the other endpoints, for example /events. We think this strikes a good balance between encouraging API clients to upgrade and them having explicit control over upgrades and a chance to test that all changes are working when they do choose to upgrade.