@c8y/client

The @c8y/client is an isomorphic (node and browser) Javascript client library for the Cumulocity IoT platform API.

Install

npm install @c8y/client

Usage

Use client.<endpoint>.list() to request listed data from the Cumulocity REST API and client.<endpoint>.detail(<id>) to request detail information. These methods always return a promise. To get an observable use list$ or detail$.

In the following sections, the default signature of these functions is described. For detailed information, refer to the complete documentation).

Get detail and list data with promises (pull)

• Example for receiving details of one mangedObject of the inventory via detail:

   const managedObjId: number = 1;
   
   (async () => {
     const {data, res} = await client.inventory.detail(managedObjId);
   })();

• Example for receiving a list of one mangedObject of the inventory via list:

   const filter: object = {
     pageSize: 100,
     withTotalPages: true
   };
   
   (async () => {
     const {data, res, paging} = await client.inventory.list(filter);
   })();

Subscribe to detail and list data with observables (push)

The detail$ and list$ functions allow to subscribe to realtime channels that omit data on each change:

• Example for receiving details of one mangedObject of the inventory via detail$:

  const managedObjId: number = 1;
   
  const detail$ = client.inventory.detail$(managedObjId);
  detail$.subscribe((data) => console.log(data));

• Example for receiving a list of one mangedObject of the inventory via list$:

  const list$ = client.inventory.list$();
  list$.subscribe((data) => console.log(data));

  Observables can be configured by adding an IObservableOptions object with these default properties:

  {
    hot: true,                                    // true = shares one network request
    realtime: true,                               // true = listen to realtime changes
    pagingStrategy: PagingStrategy.PROGRESSIVE,   // ALL = All pages are loaded
                                                  // NONE = only current page is loaded
                                                  // PROGRESSIVE = load pages with more()
    realtimeAction: RealtimeAction.FULL,          // FULL = use all CRUD realtime actions
    pagingDelay: 0                                // Delay the next page load by x ms
    realtimeFilter: undefined                     // A optional additional filter
  }

Examples

Below some examples are provided which may help you to get started. To see a complex and full implementation of the client into Angular, have a look at @c8y/cli and the new command to spin up a example application for Angular.

Requesting list data from the inventory:

import { Client } from '@c8y/client';
 
const baseUrl = 'https://demos.cumulocity.com/';
const tenant = 'demos';
const user = 'user';
const password = 'pw';
 
(async () => {
  const client = await Client.authenticate({
    tenant,
    user,
    password
  }), baseUrl);
  const { data, paging } = await client.inventory.list();
  // data = first page of inventory
  const nextPage = await paging.next();
  // nextPage.data = second page of inventory
})();

Getting an observable of the inventory endpoint:

import { Client } from '@c8y/client';
 
const baseUrl = 'https://demos.cumulocity.com/';
const tenant = 'demos';
const user = 'user';
const password = 'pw';
 
(async () => {
  const client = await Client.authenticate({
    tenant,
    user,
    password
  }), baseUrl);
  client.inventory.list$().subscribe((data) => {
    // request inventory data via fetch and adds realtime if data changes
    console.log(data);
  });
})();

Use realtime:

// realtime event
const subscription = client.realtime.subscribe('/alarms/*', (data) => {
  console.log(data); // logs all alarm CRUD changes
});
client.realtime.unsubscribe(subscription);
 
// realtime observable
const observable$ = client.realtime.observable('/alarms/*');
const observableSubscription = observable$.subscribe((data) => {
  console.log(data)); // logs all alarm CRUD changes
});
observableSubscription.unsubscribe();

Authenticate in node.js

The constructor new Client([...]) initializes a new Client which allows to request data from the API. Differently to Client.authenticate([...]) it needs a tenant given and does not verify if the login is correct. This is useful if you are developing a node.js microservice.

const auth = new BasicAuth({ 
   user: 'youruser',
   password: 'yourpassword',
   tenant: 'acme'
 });
 
 const baseUrl = 'https://acme.cumulocity.com';
 const client = new Client(auth, baseUrl);
 (async () => {
   const { data, paging, res }); =  await client.inventory.list({ pageSize: 100 });
 })();