We're happy to announce the general availability of the Cognite Data Fusion API v1.
Please help us improve our products by letting us know what you think or if you have any issues. To send us feedback, or if you need help, contact support@cognite.com.
The external ID field, (externalId
), is available in API v1 across multiple core resources: time series, assets, events, and files. You can now define a unique identifier for each data object in Cognite Data Fusion (CDF) as an optional extension to the existing id field.
The purpose of external IDs is to:
Learn more about external IDs here.
You can now upload and process 3D models with the 3D API. Initially, we support the upload of 3D models in the FBX format. More CAD formats will be added soon.
In CDF, a model is a container holding many revisions. For example, you can have a model named “Compressor”, and you can upload multiple revisions under that model as the design changes over time. When you create a revision, first upload the actual 3D file using the Files API, then create a new revision for the model linked to this file.
When you upload a new revision, CDF needs to process the 3D data to optimize it for rendering. This can take some time. We provide a status string in the revision object so you can follow the progress of the processing.
A 3D model is typically built up as a hierarchical structure. You can extract the 3D node hierarchy, and also create links from the 3D nodes to nodes in CDF’s asset hierarchy. This can be used to allow a user to click on equipment in a larger 3D model and access related sensor values or documentation.
The 3D models are typically rendered in a web application using our 3D viewer component called REVEAL. REVEAL loads a 3D model from CDF and renders it with high performance in a web browser. REVEAL has no default UI but provides a JavaScript API for flexible integration into different types of web applications.
The new version of the API has a consistent API design across all resource types, including:
You can now filter on metadata and source in search, list, and filter operations for assets, events, and files.
The time series name
attribute no longer has to be unique, and you can use the attribute as a display name instead of for lookup.
To define unique identifiers for time series, use the new externalId
attribute. For time series created through earlier API versions, the externalId field in API v1 will automatically be populated with the value of the name field. The time series you create with API v1 will require setting the new legacyName
attribute to be discoverable by older API versions.
Previously, Aseet Delete API, due to its implicit recursive nature, allowed for unintentional removal of entire asset trees. We changed this operation to be more explicit by modifying the default behavior to delete only specific leaf nodes of the asset tree. The new parameter recursive:true
allows you to explicitly enable recursive deletion of an entire asset subtree.
Support for querying asset subtrees has been removed from the API. Instead, we introduced new filters that allow for narrowing down results to a specific list of root assets. A functionality similar to querying asset subtrees will be available though SDKs. This change is an enabler for introducing support for mutable asset hierarchies in the future.
Users from previous API versions are converted to service accounts in API v1. Service accounts represent an application or service communicating with the CDF API. Each service account should represent a single application instance.
The new release limits the number of IAM (Identity and Access Management) resources you can create. If you exceed the limits, you need to remove existing resources before you can create new ones:
New versions of Cognite's official SDKs supporting API v1:
With this release, Cognite is excited to introduce a new versioning scheme for our APIs. Starting now, we will use only major versions for our API (e.g., v1, v2). We will release a new major version only if we introduce changes that are not backward compatible and may affect existing clients.
When you develop code using the CDF API, please accommodate for backward compatible (“non-breaking”) changes to ensure your application keeps working as we introduce new features and improvements.
Click here to learn more about API versioning, our policy for backwards compatibility, and the end-of-life schedule for our APIs.
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 |