Back to top

Data Broker API

This document describes the APIs using Data Broker as a standalone process. If used within dojot, the endpoints might be changed a bit. Check dojot’s documentation for more details.

Subject

In order to allow clients to consume dojot events on their own pace, dojot exposes (both internally and externally) Apache Kafka streams. To manage the set of topics exposed by the Kafka cluster, Data Broker functions as a gatekeeper to the queues, configuring the needed streams on Kafka and setting its accessibility parameters.

In order to subscribe to a given set of events, a client uses a subject. A subject is a shared human-readable identifier for the data stream one wishes to produce or consume from. From the Data Broker point of view, all subjects are equal and are just a representation of a set of events to be put on their own stream. To check the list of available subjects to consume from (as an application) please check the relevant service documentation (e.g. device-manager or iotagent).

Subject

Request Kafka topic for given subject
GET/topic/{subjectid}

Request a Kafka topic for realtime event consumption.

Example URI

GET http://localhost:80/topic/device%2Ddata
URI Parameters
HideShow
subjectid
string (required) Example: device%2Ddata

Subject whose topic is to be retrieved.

Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "topic": "admin.device-data"
}
Response  401
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": "Authentication (JWT) required for API"
}
Response  500
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": "Failed to process topic"
}

Websockets

For Websocket-based realtime consumption of events, a two-step procedure is required on the client. First, the user requests a session token, using a valid dojot JWT token to present itself to the platform. Should the user be able to access the feature, Data Broker will then generate a one-time token to be used by the client when establising the Websocket connection, through a query string parameter.

Websocket connections that do not present a valid previously agreed one-time token will be dropped.

SocketIO-based realtime events

Established connections will have two types of events defined: wildcard (all) and per device.

As a client, to be notified of changes to a specific device’s attribute values, subscribe to the device ID of the relevant device:

/*
 * Where:
 *   target is the full base url to dojot
 *   token is the one-time access token retrieved by GET /socketio
 */
var socket = socketio(target, {'query': "token=" + token, 'transports': ['websocket']});
socket.on('{deviceidhere}', (data) => {
  // handle data here
});

To be notified of changes to any device, subscribe to the wildcard message type all:

/*
 * Where:
 *   target is the full base url to dojot
 *   token is the one-time access token retrieved by GET /socketio
 */
var socket = socketio(target, {'query': "token=" + token, 'transports': ['websocket']});
socket.on('all', (data) => {
  // handle data here
});

All messages received through device-data and dojot.notification subjects will be redirected to SocketIO. To check their format and content, check iotagent-mosca documentation.

In order to receive data selectively, the following events can be subscribed:

  • all: all device events from a particular tenant

  • device-id: only events for that particular device.

  • notifications: only notifications are going to be sent. You can send back to Data Broker filters. In order to receive notifications using a SocketIO connection, a subject=dojot.notifications parameter should be added to the query string used to create the SocketIO connection.

Request authentication token
GET/socketio

Request a one-time token for connection establishment.

Example URI

GET http://localhost:80/socketio
Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "f3fa3200-355e-4c64-b300-64cef69b0576"
}
Response  401
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": "Authentication (JWT) required for API"
}

Log configuration

Retrieve/request log level changes

Log level configuration [log/config]

Retrieve current log level [GET]

  • Request

    • Headers

      Authorization: Bearer JWT

  • Response 200 (application/json; charset=utf-8)

    {"level":"debug"}

Set current log level [PUT]

  • Request

    • Headers

      Authorization: Bearer JWT

    • Body

      {
      "level": "warn"
  }

  • Response 200 (text/html; charset=utf-8)

    "Level of debugger is set to warn"

  • Request

    • Headers

      Authorization: Bearer JWT

    • Body

      {
      "level": "notalevel"
  }

  • Response 400 (text/html; charset=utf-8)

    "undefined level of debugger"

Generated by aglio on 22 Sep 2022