Changelog: API v1

This article documents all notable changes to the Cognite Data Fusion (CDF) API v1.

2019-08-21

Files

Added

  • Added support for sourceCreatedTime and sourceModifiedTime fields in files v1 endpoints.

Assets

Added

  • Allow the parent asset ID to be updated. The root asset ID must be preserved, and you can not convert a non-root asset to a root asset or vice versa.
  • Support for ignoreUnknownIds when deleting assets.

2019-08-15

3D

Added

  • Properties field for 3D nodes, extracted from uploaded 3D files.
  • Ability to filter nodes with a specific set of properties.

2019-07-24

Files

Changed

  • Allow lookup of names with length up to 256 characters (was 50) for GET /files and POST /files/search operations.
  • Allow creating and retrieving files with mimeType length up to 256 characters (was 64).

2019-07-15

Time series

Added

  • Added query parameter rootAssetIds to list time series endpoint. Returns time series that are linked to an asset that has one of the root assets as an ancestor.

2019-07-11

List of changes for initial API v1 release in comparison to previous version - API 0.5

General

Added

  • Support for externalId added across resource types. externalId lets you define a unique ID for a data object. Learn more: External IDs
  • externalIdPrefix added as a parameter to the list events, assets and files operations.
  • Richer filtering on the list assets, files and events operations.
  • Search, list and filter operations for assets, events and files now support filtering on source and metadata field values.

Changed

  • Core resources standardize on HTTP methods and URI naming for common operations such as search, partial updates, delete, list and filter
  • API responses are no longer wrapped in a top level data object.
  • Standardized pagination across resources through limit, cursor and cursorNext parameters.
  • The limit parameter no longer implicitly rounds down requested page size to maximum page size.
  • Standardized error responses and codes across all resources. Errors across CDF can be parsed into a single model.
  • Overall improvements to reference documentation. Including documented input constraints, required fields, individual attribute descriptions.

Removed

  • The sourceId field has been removed from resources. Use externalId instead of sourceId+source to define unique IDs for data objects.
  • Sorting is removed from the search operations for files, assets, events and time series. Results are sorted by relevance.
  • offset and previousCursor parameters are no longer supported for pagination across resources.
  • Fetching an asset subtree is no longer supported by files, assets, events and time series.

Assets

Added

  • Ability to select only root assets though new root filter.
  • Added the rootId field to specify the top element in an asset hierarchy.
  • Added the ability to filter by the root asset ID. This allows you to scope queries for one or many asset hierarchies.
  • List Assets allows for filtering assets belonging to set of root assets, specified by list of asset internal ids. New query parameter: rootIds.
  • Filter and Search Assets allows or filtering assets belonging to a set of root assets, specified by combination of internal and external asset identifiers. New body attribute: rootIds.

Changed

  • Updating a single asset is no longer supported through a separate endpoint. Use the update multiple endpoint instead.
  • Delete assets by default removes only leaf assets (assets without children). New parameter 'recursive' allows for enabling recursive removal of the entire subtree of the asset pointed by ID (API 0.5 behaviour).

Removed

  • Overwriting assets is no longer supported.
  • Filtering assets by their complete description is no longer supported.
  • Locating assets fuzzily by name has been removed. Instead, search for assets on the name property.
  • When searching assets, querying over both name and description in the same query is no longer supported.
  • The experimental query parameter boostName has been removed from the search for assets operation.
  • Removed the path and depth fields.

Events

Added

  • Events can now be filtered on asset ID in combination with other filters.
  • New filter rootAssetIds allows for narrowing down events belonging only to list or specified root assets. Supported by Filter and Search API

Removed

  • Events can no longer be filtered by empty description.
  • The 'dir' parameter has been removed from the search events operation.

Files

Added

  • Filtering files by assetIds in list files operations now support multiple assets in the same request.

Changed

  • Download file content has changed from HTTP GET to HTTP POST method.
  • The fileType field has been renamed to mimeType.
  • Resumable is now the default behavior for file uploads.
  • Update metadata for single files is no longer supported by a separate operation. Instead, use the update multiple operation.

Removed

  • Replace files metadata endpoint has been removed.
  • Directory has been removed as a property of files.
  • Updating the name or mimeType of a file through the update multiple files operation is no longer supported.
  • Query parameter for specifying the sort direction has been removed from list all files operations.

Raw

Changed

  • Raw has changed structure to become resource-oriented. The URL structure has changed.
  • Recursively delete of tables and rows when deleting a database is now the default behavior without a control parameter.

Time series

Added

  • Support for adding datapoints by id and externalId of time series. Adding datapoints to time series by name has been removed.
  • Add ability to update the new externalId attribute for time series.
  • Allow to set externalId during creation of time series. ExternalId requires uniqueness across time series.
  • Consolidate multiple APIs to allow adding datapoints into a single endpoint. Allows datapoints to be added to multiple time series at the same time.
  • Retrieve data points by using id and externalId of the time series.
  • Time series created through API v1 are not discoverable by API 0.3, 0.4, 0.5 and 0.6 by default. Introduce the option to enable this compatibility by setting new attribute - legacyName on time series creation. Value is required to be unique.

Changed

  • Get latest datapoints has been reworked. Introduces support for id and externalId lookup as well retrieval for multiple time series within the same request.
  • Time series name is no longer limited by uniqueness. Note that time series (meta objects) created by API v1 will not be discoverable by older API versions.
  • Delete time series endpoint has been redesigned to allow deletion of multiple time series by id and externalId.
  • Delete single and multiple datapoints endpoint has been redesigned and consolidated into a single endpoint. New delete allows selection of multiple time series and time ranges by id and externalId. Selecting by name is no longer available.
  • Update multiple time series restructured to support lookup by externalId.
  • Retrieve time series by ID endpoint restructured adding the ability to get time series by externalId.
  • Set limit for data point value to min -1E100, max 1E100.

Removed

  • Experimental feature for performing calculations across multiple time series (synthetic time series), function and alias attributes are no longer available.
  • The experimental query parameter boostName has been removed from search operation.
  • Short names for aggregate functions are no longer supported.
  • Ability to remove time series by name have been removed as names are no longer unique identifiers.
  • Select multiple time series and time ranges by name is no longer available.
  • The ability to update isString and isStep attributes is removed. The attributes are not intended to be modified after creation of time series.
  • The endpoint for updating single time series is removed. Use the update multiple time series endpoint instead.
  • Remove ability to overwrite time series object by id. Use the update multiple time series endpoint instead.
  • The ability to retrieve time series matching by name has been removed. Use externalId instead.
  • The ability to retrieve by id from a single time series has been removed. Use retrieve multiple datapoints for multiple time series instead.
  • The ability to retrieve time-aligned datapoints through "dataframe" API has been removed. Similar functionality is available through our supported SDKs.
  • The ability to add datapoints to time series by name has been removed.
  • The ability to look up by time series name has been removed.

IAM (Identity and access management)

Added

  • The login status endpoint includes the ID of the API key making the request (new attribute: apiKeyId), if the request used an API key.

Changed

  • The user resource type has been replaced with service accounts. Users from previous API versions are equivalent to service accounts.
  • Adding, listing and removing users from a group has been replaced by equivalent operations for service accounts.
  • Retrieve project returns a single object instead of a list.
  • API keys endpoints for list/create rename userId attribute to serviceAccountId.

Removed

  • List and create groups no longer use the permissions and source attributes.

3D

Added

  • New 3D API lets you upload and process 3D models. Supported format: FBX.
  • Ability to create and maintain multiple revisions for the 3D models.
  • API for mapping relationships between 3D model nodes and asset hierarchy.
Last Updated: 8/21/2019, 6:44:12 PM