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 subjectGET/topic/{subjectid}
Request a Kafka topic for realtime event consumption.
Example URI
- subjectid
string
(required) Example: device%2DdataSubject whose topic is to be retrieved.
Headers
Authorization: Bearer JWT
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"topic": "admin.device-data"
}
401
Headers
Content-Type: application/json; charset=utf-8
Body
{
"error": "Authentication (JWT) required for API"
}
500
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, asubject=dojot.notifications
parameter should be added to the query string used to create the SocketIO connection.
Request authentication tokenGET/socketio
Request a one-time token for connection establishment.
Example URI
Headers
Authorization: Bearer JWT
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"token": "f3fa3200-355e-4c64-b300-64cef69b0576"
}
401
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"