Cognite documentation

# CDF API v1

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.

# New features

# External ID

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:

  • Insert data without creating duplicate entries.
  • Avoid extra lookups when updating data.
  • Maintain relationships between data objects from source systems.
  • Give you a way of performing key-value lookups with keys you control, and that works the same across core resources.

Learn more about external IDs here.

# 3D API

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.

# Improvements

# Structural improvements

The new version of the API has a consistent API design across all resource types, including:

  • Consistent design and behavior for standard endpoints, with functionality such as insert, search, list, partial updates, delete.
  • Common naming of query parameters, and request and response attributes.
  • Shared pagination pattern with limit and cursor.
  • Consistent use of response codes.
  • Single error type for API.
  • Documentation improvements: constraint definitions for input parameters, required fields, more detailed attribute documentation,
  • A simplified API that provides one way to perform specific tasks.

# Search and filtering improvements

You can now filter on metadata and source in search, list, and filter operations for assets, events, and files.

# Time series allow for non-unique names

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.

# Safe asset deletion

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.

# Asset subtree query removal

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.

# Service accounts

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.

# Identity and access management - limits

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:

  • Number of API keys per service account: 5.
  • Number of service accounts per project: 700.
  • Number of groups per project: 50 (undeleted groups).
  • Number of security categories per project: 1000.

# New SDK versions

New versions of Cognite's official SDKs supporting API v1:

# New API versioning

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.

# Deprecating API 0.3-0.6

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

# Additional resources