Using the API

Our RESTful web API enables you to access resources in Cognite Data Fusion. To read or write to a resource, you construct requests that look like this:

https://api.cognitedata.com/api/{version}/projects/{project}{resource}?query-parameters/ 
1

Where:

  • HTTP method - The HTTP method used on the request to Cognite Data Fusion.
  • {version} - The version of the API your application is using.
  • {project} - The project identifier for the resources in Cognite Data Fusion that you're referencing.
  • {resource} - The resource in Cognite Data Fusion that you're referencing.
  • query-parameters - An optional set of parameters to modify the request or response.

When you make a request, Cognite Data Fusion returns a response that includes:

  • Status code - An HTTP status code that indicates success or failure. For details about HTTP error codes, see Errors.
  • Response message - The data that you requested or the result of the operation. The response message can be empty for some operations.
  • Pagination - If your request returns a lot of data, you need to page through it. For details, see Paging.

In this article:

HTTP methods

Cognite Data Fusion uses the HTTP method on your request to determine what your request is doing. The API supports the following methods.

Method Description
GET Read data from a resource.
POST Create a resource, or perform an action.
DELETE Remove a resource.
PUT Replace a resource with a new one.

Version

Cognite Data Fusion currently supports two versions: v0.5 and v0.6 (experimental).

  • v0.5 includes generally available features. Use this version for all production apps.
  • v0.6 (experimental) includes features that are currently in preview. Because we might introduce breaking changes to our beta APIs, we recommend that you use this version only to test apps that are in development. Do not use this version in your production apps.

Project

Projects are used to separate customers from one another, and all resources in Cognite Data Fusion are linked to a project. A customer usually has only one project. The project object contains configuration for how to authenticate users.

Automatically assigned object ids are unique only within each project.

Resources

Your URL will include the resource or resources you are interacting with in the request, such as assets, files, events, and timeseries.

For more information about resource types, see About resource types and the resource reference topics.

Cursors and pagination

Results from the APIs are wrapped in one of two data types: Data or DataWithCursor.

DataWithCursor has cursors that allows you to navigate through multiple pages of results. The cursor is a random string that can be copied and sent with subsequent requests to navigate through the pages of results.

Errors

Errors in the API are returned using standard HTTP status codes, and with a JSON error response object:

{
  "error": {
    "code": 0,
    "message": "string",
  }
}
1
2
3
4
5
6

IP addresses for the API

The IP addresses for our APIs are not static and will change as we evolve our architecture and extend our service offerings. We will do our best to keep the changes to a minimum.

If you want to limit outbound traffic to api.cognitedata.com only, the IP addresses for the current and future APIs are:

35.187.184.117
34.76.254.249
1
2

We are working on exposing updated lists of our API addresses automatically, but until that is in place, check back here once a month to verify if there are any changes.

Other IP addresses

Some of our API endpoints, such as the Files endpoint, return a link to a Google Cloud resource. This is important to ensure that uploads fully leverage the Google Cloud services as efficiently as possible.

To fully use all our API endpoints, most importantly Files, you must also open up for certain Google Cloud IP addresses. Google publishes a list of these IP ranges through DNS: https://cloud.google.com/compute/docs/faq#find_ip_range.

Because Cognite Data Fusion resides on the Google Cloud, you will also open for our API endpoints when you open for the Google Cloud IP ranges.

Last Updated: 4/12/2019, 10:53:12 AM