Dojot 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 to check all of them.
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/partitions exposed by the kafka cluster, the data-broker component 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 ID for realtime event consumption
Example URI
- subjectid
string(required) Example: device%2DdataSubject whose topic is to be retrieved.
Headers
Authorization: Bearer JWT200Headers
Content-Type: application/json; charset=utf-8Body
{
"topic": "c9b2c688-9e40-4032-877a-3d262acba9d0"
}Websockets ¶
For websocket based real time 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 querystring param.
Websocket connections that do not present a valid previously agreed one-time token will be dropped.
Socket-io 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('abcd', (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
});Request authentication tokenGET/socketio
Request a one-time token for connection establishment.
Example URI
Headers
Authorization: Bearer JWT200Headers
Content-Type: application/json; charset=utf-8Body
{
"token": "f3fa3200-355e-4c64-b300-64cef69b0576"
}