API versions

Learn about our API versioning, our policy for backwards compatibility, and the end-of-life schedule for our APIs.

In this article:

Current API versions

We currently offer these versions of the Cognite Data Fusion API.

API version Status Description
API v1 Stable Recommended for production environments.

We will keep adding backwards-compatible (non-breaking) changes to the stable API. If we change the API in a backwards-incompatible way, we will release those changes as a new major API version.

Supported by JavaScript SDK 2.x.x and Python SDK 1.x.x or newer

The current stable API will be available for a 12 months after the release of the next major API version.
API 0.6 (experimental) Deprecated Do not use in production environments.

This version showcases experimental features.

Scheduled to be removed
API 0.5 Deprecated Previous stable API.

Scheduled to be removed
API 0.4 Deprecated Previous stable API.

Scheduled to be removed
API 0.3 Deprecated Previous stable API.

Scheduled to be removed
Playground Unstable Do not use in production environments.

This version showcases our newest ideas, experimental/beta features and demos.

Interface is highly unstable and constantly changing.

End-of-life for API versions

The following API versions are scheduled for end-of-life. If you have applications, solutions, or demos using these APIs and SDKs, you need to migrate to the current stable API and accompanying SDKs. If you have any questions or need assistance please contact support@cognite.com

The APIs will not be available after their end-of-life dates.

API version SDK version End-of-life date
API 0.5
API 0.6
Python SDK 0.x.x or earlier
JavaScript SDK 1.x.x or earlier
January 02, 2020
API 0.3
API 0.4
Python SDK 0.11.x or earlier September 10, 2019

Backwards compatibility

If we change the current stable API in a way that is backwards-incompatible, we will release those changes as part of a new major API version. The current stable API will be available for 12 months after the release of the next major API version to provide a migration period for our users.

A backwards-incompatible change is a change that causes a previously successful request, or successful parsing of the response, to fail or give different results after the change is released.

Backwards-compatible (non-breaking) changes

We consider the following to be examples of backwards-compatible (non-breaking) changes:

  • Increasing the request limits.
  • Adding properties to the response body.
  • Adding properties to the request body (as long as it doesn't affect previous requests).
  • Adding support for more query parameters (as long as it doesn't affect previous requests).

Backwards-incompatible (breaking) changes

We consider the following to be examples of backwards-incompatible (breaking) changes:

  • Removing an endpoint.
  • Removing a property in the response.
  • Changing the error response format (not the status code).
  • Changing the status code from 2xx to another 2xx.
  • Reducing the limit on a request (not the response). Example: the number of assets to retrieve by assetIds.
  • Changing the name of query parameters and body properties.
  • Changing the sort order if the original order was expected by the user.
Last Updated: 8/19/2019, 8:29:01 AM