Skip to content

Migrate from idlab-iot1

To ease the transition to Obelisk, you can find some highlights of the most notable changes in the sections below.

Client auth procedure

There were some changes to the authentication procedure for clients (services) authenticating as themselves. They now require a 2-step auth procedure, in line with the procedure that was in place for clients authenticating on behalf of their users. The new (consolidated) procedure is described in the Security > Auth details section.

New Typescript client

Together with the new stack, there is a new client that has to be used. Once again, this client is meant for browser applications that log in on behalf of their users. It can be found on npm under @obelisk/client. There also is an optional Angular package available under @obelisk/ngx.

The major change in the new client is the authentication and creation. Because of the changes in the auth flow, the options given to the client have been simplified into one ObeliskOptions object. A new client is constructed by using the 'new' keyword (no longer static create).

1
2
3
4
5
6
7
const options: ObeliskOptions = {
    host: 'https://obelisk.ilabt.imec.be',
    apiVersion: 'v1',
    realm: 'idlab-iot',
    clientId: 'my-client'
};
let client: ObeliskClient = new ObeliskClient(options);

After that you first have to initialize the client with the backend, allowing it to asynchronously fetch all needed configuration.

1
2
3
this.client.init().subscribe({
    next: _ => console.log('client is initialized')
});

Besides these steps, the API of the client has not changed, you still create Endpoints as you used to. More information can be found on the npm pages and the client documentation.

New clientSecrets

If your application was sending values to the stack, it will have to be changed to send to Obelisk. For this you can use the old clientId, however the clientSecret will have to be re-generated. The best way to do this, is via a ticket.

Ingest API

If you send values to our platform, we highly suggest you to read the section on sending values. It has all information you need to start sending values again as soon as possible. Below is a short summary of the most notable changes.

New path

The ingest API path used to be /api/v1/ingest. New in Obelisk is scoped ingest, which means that values is now sent directly to a scope. For that reason the ingest API path is changed to /api/v2/scopes/{scopeId}/ingest. You will have to know the scope you send to.

New format

The format of ingest has also slightly changed. It now looks like this:

1
2
3
4
5
6
7
// Array of: [timestamp, metric, things, value, *[long, lat], *elevation] 
// (*: optional)
[
  [1526569675478, "button.pressed", "demo.things.button1", true],
  [1526569675478, "humidity.rh", "demo.things.multisensor1", 435, [4.41818582, 51.22154617]],
  [1526569675478, "temperature.celsius", "demo.things.multisensor1", 12.0, [4.41818582,51.22154617], 4.3]
]

Input validation

If sent values did not pass validation, a 400 Bad Request will be returned. The body of the response will contain information on what went wrong.