npm

Does your artifact manager get in the way? Join us on Oct. 8 at 10am PT, to discuss how npm can help.Sign up »

@c8y/client

1004.6.13 • Public • Published

@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)

Method Description Parameters Return
detail(entityOrId) Request detail data of a specific entity. entityOrId: string | number | IIdentified: An object which contains an id or an id as number or string. Promise<IResult<TData>>: The list as Promise wrapped in an IResult. IResultList contains data and response.
list(filter) Request a list of data with an optional filter. filter:object: (optional) A filter for paging or filtering of the list. Promise<IResultList<TData>>: The list as Promise wrapped in an IResultList. IResultList contains data, response and paging.
  • 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:

Method Description Parameters Return
detail$(entityOrId, options) Returns an observable for detail data of one entity entityOrId: string | number | IIdentified: An object which contains an id or an id as number or string.
options: IObservableOptions: (optional) An configuration object to define the observable.
Observable<TData>>: The list as subscribable observable.
list$(filter, options) Returns an observable for a list of entities. filter: object: (optional) A filter for paging or filtering of the list (optional).
options: IObservableOptions: (optional) An configuration object to define the observable.
ObservableList<TData>>: The list as subscribable observable.
  • 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 });
 })();

install

npm i @c8y/client

Downloadsweekly downloads

47,299

version

1004.6.13

license

UNLICENSED

last publish

collaborators

  • avatar
Report a vulnerability