@c8y/client
The @c8y/client is an isomorphic (node and browser) Javascript client library for the Cumulocity IoT platform API.
Installation
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 managed object of the inventory via
detail
:const managedObjId: number = 1;async {const data res = await clientinventory;}; -
Example for receiving a list of one managed object of the inventory via
list
:const filter: object =pageSize: 100withTotalPages: true;async {const data res paging = await clientinventory;};
Accessing a microservice with the Fetch API
The client internally uses the Fetch API. By accessing this core function, you can do any authenticated request to any resource. Standalone you can use core.client.fetch(url, options)
and in @c8y/ngx-components/data
for Angular you simply need to inject the FetchClient
:
{} // di async { const options: IFetchOptions = method: 'GET' headers: 'Content-Type': 'application/json' ; const response = await thisfetchClient; // Fetch API Response}
All fetch responses with application/json
content type can be parsed to JSON objects. Find more information on handling fetch responses in the MDN documentation.
Authentication strategy
In the Cumulocity platform we currently allow two ways to authenticate:
- Basic Auth: The authentication header is injected into each request.
- Oauth: The client doesn't know about the authentication header. The header is set in a cookie.
To quickly get you started, the @c8y/client provides a shorthand static function which always uses Basic Auth and verifies the login directly:
await Client url);
It internally creates a client instance and tries to contact the API to verify if the given credentials are correct. In some cases you need to use a more fine-grained authentication, e.g. when you don't know which authentication strategy the user is going to use. In this case you need to construct an own instance of the client and pass the authentication strategy to it:
const baseUrl = 'https://acme.cumulocity.com'; const client = baseUrl; // use here `new BasicAuth()` to switch to Basic Auth try const data paging res = await clientuser; console; catchex console
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 managed object of the inventory via
detail$
:const managedObjId: number = 1;const detail$ = clientinventory;detail$; -
Example for receiving a list of one managed object of the inventory via
list$
:const list$ = clientinventory;list$;Observables can be configured by adding an
IObservableOptions
object with these default properties:hot: true // true = shares one network requestrealtime: false // true = listen to realtime changespagingStrategy: PagingStrategyPROGRESSIVE // ALL = All pages are loaded// NONE = only current page is loaded// PROGRESSIVE = load pages with more()realtimeAction: RealtimeActionFULL // FULL = use all CRUD realtime actionspagingDelay: 0 // Delay the next page load by x msrealtimeFilter: 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:
; const baseUrl = 'https://demos.cumulocity.com/';const tenant = 'demos';const user = 'user';const password = 'pw'; async { const client = await Client; const data paging = await clientinventory; // data = first page of inventory const nextPage = await pagingnext; // nextPage.data = second page of inventory};
Getting an observable of the inventory endpoint:
; const baseUrl = 'https://demos.cumulocity.com/';const tenant = 'demos';const user = 'user';const password = 'pw'; async { const client = await Client; clientinventory;};
Using realtime:
// realtime eventconst subscription = clientrealtime;clientrealtime; // realtime observableconst observable$ = clientrealtime;const observableSubscription = observable$;observableSubscription;
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 = user: 'youruser' password: 'yourpassword' tenant: 'acme' ; const baseUrl = 'https://acme.cumulocity.com'; const client = auth baseUrl; async { const data paging res ; = await clientinventory; };