Publishing & Subscribing to data topics

Custom data topics can be defined allowing users to subscribe to various location data streams.

To publish your data onto cells first create a topic to collect the data.

The following requests are authenticated by providing your api key in the apikey header. Visit https://map.unl.global/developer to create an apikey.

Publishing data

Create a topic

POST https://api.unl.global/v1/pubsub/topics

Request body

{
"Name": "Example topic",
"Description": "Description for the topic data"
}

Response

{
"isSuccess": true,
"data": {
"id": 1,
"name": "Example topic",
"description": "Description for the topic data",
"createdAt": "2020-10-09T09:05:08.937692",
"userId": "auth0|5d9dddbe0935d60e2267fbef"
}
}

List topics

GET https://api.unl.global/v1/pubsub/topics

Response

{
"isSuccess": true,
"data": {
"limit": 10,
"offset": 0,
"totalCount": 2,
"items": [{
"id": 1,
"name": "Example topic",
"description": "Description for the topic data",
"createdAt": "2020-10-09T09:05:08.937692",
"userId": "auth0|5d9dddbe0935d60e2267fbef"
}]
}
}

Get topic

GET https://api.unl.global/v1/pubsub/topics/:topicId

Response

{
"isSuccess": true,
"data": {
"id": 1,
"name": "Example topic",
"description": "Description for the topic data",
"createdAt": "2020-10-09T09:05:08.937692",
"userId": "auth0|5d9dddbe0935d60e2267fbef"
}
}

Delete topic

DELETE https://api.unl.global/v1/pubsub/topics/:topicId

Publish data to topic

Publish data onto a unl location. The Data field can consist of any json object. Any active subscriptions on this location and topic will recieve a webhook request with the published data.

POST https://api.unl.global/v1/pubsub/topics/:topicId/publish

Request body

{
"LocationId":"u1ku2k",
"Data": {
"field_a": "value 1",
"field_b": [ "value 2", "value 3" ],
"field_c": {
"field_c_a": "sub value"
}
}
}

Subscribing to data

Create subscription

It is possible to subscribe to a topic for a particular location. When an event occurs within the subscribed area, the event data will be sent to the provided webhook address via a POST request.

A custom webhook header can be configured for each subscription, this is useful in cases where the webhook endpoint is protected by an authentication key.

An optional SecretToken may be set per topic. If provided, an additional header unl-signature will be present with a hash signature than can be used to verify that the data came from unl and was not tampered with. The signature is calculated by conatenating the timestamp, secret token, and payload, then creating a sha256 hexidecimal hash. The example nodejs program below demonstrates how to revieve and verify messages.

unl-signature:t=1583751015,digestV1=6d46503d2296f5b3091ce0da361b44c5a626d02ba4353eed7017d5e292cfc295
POST https://api.unl.global/v1/pubsub/subscriptions

Request body

{
"WebhookAddress": "",
"WebhookHeader": "x-custom-header:custom_header_value",
"SecretToken": "my_secret_token",
"LocationIds": [
"u173z",
"u173y",
"u173w"
],
"TopicId": 1
}

Example webhook endpoint with signature validation

const express = require('express');
const bodyParser = require('body-parser');
const crypto = require('crypto');
const config = {
port: 3000,
headerName: 'unl-signature',
secret_token: 'my_secret_token'
};
const app = express();
app.use(bodyParser.json());
app.post('/', (req, res) => {
try {
const signature = Object.fromEntries(req.headers[config.headerName].split(',').map(x=>x.split('=')));
const hash = crypto.createHash('sha256').update(`${signature.t}.${config.secret_token}.${JSON.stringify(req.body)}`).digest('hex');
const isValid = signature.digestV1 === hash;
console.log(`Signature: ${signature.digestV1}`);
console.dir(req.body);
console.log(isValid ? 'VALID SIGNATURE' : 'INVALID SIGNATURE');
res.status = 200;
}
catch (err) {
res.status = 500;
console.error(err);
}
});
app.listen(config.port, () => console.log(`Example app listening on port ${config.port}!`));