README.md

Cognite Javascript SDK

The package @cognite/sdk provides convenient access to the stable Cognite API from applications written in client- or server-side javascript.

The SDK supports authentication through api-keys (for server-side applications) and bearer tokens (for web applications). See Authentication Guide.

Installation

Install the package with yarn:

$ yarn add @cognite/sdk

or npm

$ npm install @cognite/sdk --save

Usage

const { CogniteClient } = require('@cognite/sdk');

Using ES modules

import { CogniteClient } from '@cognite/sdk';

Using typescript

The SDK is written in native typescript, so no extra types need to be defined.

Quickstart

Web

import { CogniteClient, CogniteAuthentication } from '@cognite/sdk';

async function quickstart() {
  const project = 'publicdata';
  const legacyInstance = new CogniteAuthentication({
    project,
  });

  const getToken = async () => {
    await legacyInstance.handleLoginRedirect();
    let token = await legacyInstance.getCDFToken();
    if (token) {
      return token.accessToken;
    }
    token = await legacyInstance.login({ onAuthenticate: 'REDIRECT' });
    if (token) {
      return token.accessToken;
    }
    throw new Error('error');
  };

  const client = new CogniteClient({
    appId: 'YOUR APPLICATION NAME',
    project,
    getToken,
  });

  const assets = await client.assets.list().autoPagingToArray({ limit: 100 });
}
quickstart();

For more details about SDK authentication see this document. Also, more comprehensive intro guide can be found here

Backend

const { CogniteClient } = require('@cognite/sdk');

async function quickstart() {
  const client = new CogniteClient({
    appId: 'YOUR APPLICATION NAME',
    apiKeyMode: true,
    getToken: () => Promise.resolve('YOUR_SECRET_API_KEY'),
  });

  const assets = await client.assets.list().autoPagingToArray({ limit: 100 });
}
quickstart();

Documentation

• API reference documentation
• JS SDK reference documentation

Best practices

No submodule imports

We highly recommend avoiding importing anything from internal SDK modules.

All interfaces and functions should only be imported from the top level, otherwise you might face compatibility issues when our internal structure changes.

Bad:

import { CogniteAsyncIterator } from '@cognite/sdk/dist/src/autoPagination'; // ❌
import { AssetsAPI } from '@cognite/sdk/dist/src/resources/assets/assetsApi'; // ❌

let assetsApi: AssetsAPI; // ❌

Good:

import { CogniteAsyncIterator } from '@cognite/sdk'; // ✅

let assetsApi: CogniteClient['assets']; // ✅

We recommend the usage of eslint to ensure this best practice is enforced without having to memorize the patterns:

.eslintrc.json:

"rules": {
  "no-restricted-imports": ["error", { "patterns": ["@cognite/sdk/**"] }]
}

The API reference documentation contains snippets for each endpoint, giving examples of SDK use. See also the samples section in this repo.

Guides

• Migration guide on how to migrate from version 1.x.x to version 2.x.x.
• Migration guide from version 2.x.x to version 3.x.x.