iot-stack-client

IoT-stack Client

A client library written in Typescript to interact with the IoT-stack API. Link back to the full documentation here.

Prerequisites

This library makes use of RxJS (Reactive Extensions for JavaScript). RxJS is a library for reactive programming using observables that makes it easier to compose asynchronous or callback-based code (RxJS). We make use of version 6 and its syntax: no more use of method chaining, put using the pipe() operator instead), for more information on that see the RxJS 6 migration section.

RxJS 6 comes as a peer dependency.

Overview

The client has a clear purpose:

• Make it easier to do follow up requests on Temporal Pages (see IoT-stack documentation).
• Do the heavy lifting on authentication and authorization

The client uses keycloak's javascript library to connect to our back-end keycloak Authorization Server. This should handle:

• Logging in to a supported Identity Provider (eg. Google)
• Getting the access token
• Getting the RPT token
• Refreshing tokens when needed
• Login/logout support

With the client you create Endpoints. These endpoints can be acted on with methods like execute() or get(). An endpoint takes an API uri as argument. This means that the HTTP REST api is as important to you, as this API.

Installation

npm install iot-stack-client rxjs --save

Usage

To start you need to create an IotClient instance with a proper options object. Do this through the static create facory function. This will return an Observable, because setting everything up is an asnychronous operation. By subscribing to the client you know for sure that it is initialized.

import { pipe } from 'rxjs';
import { share, flatMap } from 'rxjs/operators';

# Create shareable observable. (caches the client object)
const options = {
    config: {
        host: 'https://idlab-iot.tengu.io',
        apiVersion: 'v1',
        realm: 'idlab-iot',
        clientId: 'my-client',
    },
    initOptions: {
        checkLoginIframe: false
    }
}
let clientObs = IotClient.create(options).pipe(share());

# Use it to request the scopes you have access to
clientObs
    .pipe(
        flatMap(client => client.endpoint('/context/scopes').get())
    )
    .subscribe(
        console.log,
        console.error
    )

The .pipe(share()) operator at the end allows you to subscribe with different listeneres, without reinitializing the client each time. This way you can start every interaction with the client as an rx chain from clientObs.

How to

In the Swagger UI (see full IoT-stack documentation) you can see which datastructures are returned.

Datastructures

Purpose	Use method	Description
Pull TemporalPage	.temporalPageEndpoint(uri) : TPageEndpoint	Getting data in the TemporalPage format
Stream TemporalPage data	.streamEndpoint(uri): StreamEndpoint	Stream current data in TemporalPage format
Use any other API call	.endpoint(uri) : Endpoint	Execute any other API call

Methods

Object	Method	Description
TPageEndpoint	.execute(): Obserable<TPageResponse>	Executes the call, if a range was requested, it will automatically request the whole range.
StreamEndpoint	.connect(options) : Observable<TPage>	Connects with this endpoint as an eventsource. Use options to filter the stream.
Endpoint	.get(): Observable<AjaxResponse>	Executes a get on a normal endpoint.
Endpoint	.post(body): Observable<AjaxResponse>	Executes a post on a normal endpoint.
Endpoint	.put(body): Observable<AjaxResponse>	Executes a put on a normal endpoint.
Endpoint	.delete(): Observable<AjaxResponse>	Executes a delete on a normal endpoint.

All these methods will add Auth headers as needed. And try to refresh the token if it expired.

Time ranges

To request timerange, you do what you would do with the HTTP REST API. For instance:

# Make timestamp eg. with moment library
const now = moment().valueOf();
const yesterday = moment().subtract(1,'day').valueOf();
const uri = '/scopes/myscope/locations/u155/airquality.no2/events?from='+yesterday+'+&to='+now;

# Use shared observable
clientObs
    .pipe(
        flatMap(client => client.temporalPageEndpoint(uri).execute())
    )
    .subscribe(
        data => console.log(data),
        error => console.error(error),
        () => console.log('done')
    );

If you are logged in it will handle all the tokens in the headers for you.