Dojot data broker API

Subject Profiles  ¶

Subject profiles are used to define how topics will be created when requesting one for a particular subject. For instance, let’s say that current deploy must prioritize data sent by devices (received, processed and published by IoT agents). In order to do this, the system administrator might want to create a profile to device-data subject, which is the one used by IoT agent, adding more partitions to it. Therefore, whenever a new IoT agent requests a topic to DataBroker, it will create a new topic (if it doesn’t exist already) this new configuration. The administrator can set different profiles to different tenants associated to the same subject.

There are two ways to configure a subject profile:

1. Setting a default value for number of partitions and replication factor. Using this scheme will distribute all partitions evenly to all Kafka brokers in the cluster. The message format is as follows:

   {
       "num_partitions": 4,
       "replication_factor" : 2
   }

This message indicates that the topic will have 4 partitions and each one will have two replicas.

2. Setting a mapping of partitions and brokers: this scheme allows an administrator to set the broker which will host a particular partitions (first element is the preferred partition leader) and its replicas. The message format is as follows:

   {
       "replica_assignment": {
           "1": [ 1, 2, 3],
           "2": [ 4, 5, 6]
       }
   }

This message indicates that the topic will have 2 partitions. The first partition will be hosted by brokers 1 (preferred partition leader), 2 and 3 and the second one will be hosted by brokers 4 (preferred partition leader), 5 and 6.

This mapping will be used as a suggestion to Kafka brokers. As noted in its documentation, it is not guaranteed that this mapping will be exactly the configured scenario.

The schemes are mutually exclusive. Also, these APIs are accessible only by users in admin tenant (only system administrator can use them).

Default values are one partition per topic, no replication.

Authorization: Bearer JWT

Content-Type: application/json; charset=utf-8

{
  "special-user": {
    "replica_assignment": {
      "1": [
        1,
        2,
        3
      ],
      "2": [
        4,
        5,
        6
      ]
    }
  },
  "*": {
    "num_partitions": 2,
    "replication_factor": 1
  }
}

Content-Type: application/json; charset=utf-8

{
  "error": "Missing mandatory authorization header in profile request"
}

Content-Type: application/json; charset=utf-8

{
  "message": "Could not find profiles for this subject"
}

Content-Type: application/json; charset=utf-8

{
  "message": "error",
  "details": "internal error"
}

Authorization: Bearer JWT

{
  "special-user": {
    "replica_assignment": {
      "1": [
        1,
        2,
        3
      ],
      "2": [
        4,
        5,
        6
      ]
    }
  },
  "*": {
    "num_partitions": 2,
    "replication_factor": 1
  }
}

Content-Type: application/json; charset=utf-8

{
  "message": "Set configs successfully"
}

Content-Type: application/json; charset=utf-8

{
  "error": "Missing mandatory authorization header in profile request"
}

Edit Profile  ¶

Authorization: Bearer JWT

{
  "special-user": {
    "replica_assignment": {
      "1": [
        1,
        2,
        3
      ],
      "2": [
        4,
        5,
        6
      ],
      "3": [
        7,
        8,
        9
      ]
    }
  }
}

Content-Type: application/json; charset=utf-8

{
  "message": "Configs edited/created successfully"
}

Content-Type: application/json; charset=utf-8

{
  "error": "Missing mandatory authorization header in profile request"
}

Subject  ¶

Authorization: Bearer JWT

Content-Type: application/json; charset=utf-8

{
  "topic": "c9b2c688-9e40-4032-877a-3d262acba9d0"
}

Content-Type: application/json; charset=utf-8

{
  "error": "missing mandatory authorization header in get request"
}

Content-Type: application/json; charset=utf-8

{
  "error": "failed to process topic"
}

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('{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 Socket-io. 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 sent back to data-broker filters. In order to receive notifications using a socket io connection, a subject=dojot.notifications parameter should be added to the query string used to create the socket.io connection.

Authorization: Bearer JWT

Content-Type: application/json; charset=utf-8

{
  "token": "f3fa3200-355e-4c64-b300-64cef69b0576"
}

Content-Type: application/json; charset=utf-8

{
  "error": "missing mandatory authorization header in socketio request"
}