The @c8y/client is an isomorphic (node and browser) Javascript client library for the Cumulocity IoT platform API.
npm install @c8y/client
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.
In the following sections, the default signature of these functions is described. For detailed information, refer to the complete documentation).
Method | Description | Parameters | Return |
---|---|---|---|
detail(entityOrId) |
Request detail data of a specific entity. | `entityOrId: string | number |
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 client.inventory.detail(managedObjId);
})();
Example for receiving a list of one managed object of the inventory via list
:
const filter: object = {
pageSize: 100,
withTotalPages: true
};
(async () => {
const {data, res, paging} = await client.inventory.list(filter);
})();
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
:
constructor(private fetchClient: FetchClient) {} // di
async getData() {
const options: IFetchOptions = {
method: 'GET',
headers: { 'Content-Type': 'application/json' }
};
const response = await this.fetchClient.fetch('/service/my-service', options); // 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.
In the Cumulocity platform we currently allow two ways to authenticate:
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.authenticate({ tenant, user, password }, 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 = new Client(new CookieAuth(), baseUrl); // use here `new BasicAuth()` to switch to Basic Auth
try {
const { data, paging, res } = await client.user.currentUser();
console.log('Login with cookie successful');
} catch(ex) {
console.log('Login failed: ', ex)
}
Note: As the default login mode for UI is OAI, you usually don't need to authenticate via Basic Auth.
To login via OAI and use a Cookie for authentication you can use:
const client = await Client.getOAuthInternalClientViaCookie({ tenant, user, password }, url);
To login via OAI and use the authentication header for authentication you can use:
const client = await Client.authenticateViaOAuthInternal({ tenant, user, password }, url);
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.
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
})();
// realtime event
const subscription = client.realtime.subscribe('/alarms/*', (data) => {
console.log(data); // logs all alarm CRUD changes
});
client.realtime.unsubscribe(subscription);
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 });
})();