Protocol Structure

Hivekit uses a simple, JSON-based message format. Each message consists of an array of actions, e.g.

[{
  typ: 'obj', // type == object
  act: 'set', // action == set (quick way to UPSERT)
  id: 'rider/SadeIbrahim', // object id
  rea: 'lagos', // realm id
  loc: { lon: 3.37590, lat: 6.51309 } // location
},{
  typ: 'obj',
  act: 'set',
  id: 'rider/AyofemiMusa',
  rea: 'lagos',
  loc: { lon: 3.37592, lat: 6.51317 }
}]

The keys in Hivekit's messages are always abbreviated to three-letter codes to decrease overall message size. Client libraries then expand them into human-readable values. [You can find the full list of fields and shortcodes here.]

Request/Response & Correlation IDs

Hivekit messages can be sent in response to a request or can be sent by the server or other clients as an update. To map requests to responses, you can add a unique correlation id cid to your messages that will be returned as a response by the server.

// sent to the server
[{
  typ: 'obj',
  act: 'cre',
  id: 'object-a-oLO5Cmr5kRLIl_EinZ68H',
  rea: 'realm-a-LZl82XWWycWStqokUjWez',
  lab: 'Object A Label',
  loc: { lon: 13.404954, lat: 52.520008 },
  dat: { type: 'scooter', charge: 0.5 },
  cid: 'LZuwP3tAeDaAYnbEapkOG' // this correlation id will help us map the server's response to this request
}]

// received from the server
[{
  id: 'object-a-oLO5Cmr5kRLIl_EinZ68H', // id for the object
  cid: 'LZuwP3tAeDaAYnbEapkOG', // correlation id for the request
  res: 'suc' // result = success
}]

Persistent Connections need to send an auth message first

There is one message in Hivekit that breaks the schema - and that's the initial authentication message.

[There are several non-message-based ways to authenticate your client with Hivekit, e.g. Cookies or Authorization headers.] But, if you choose to authenticate by sending your authentication token as a message, your first message must look like this:

Bearer TOKEN

The reason is that Hivekit will keep your connection initially in a "quarantine" state and won't even parse incoming messages until the authentication token is received. Here's how you would connect and authenticate a Websocket in NodeJS

import WebSocket from "ws"; // node only - in the browser, just use window.WebSocket
const ws = new WebSocket('wss://api.hivekit.io/v1/ws')
ws.on('open', () => {
    ws.send('Bearer YOUR_API_TOKEN');
})
ws.on('message', msgBuffer => {
    JSON.parse(msgBuffer.toString()).forEach(msg => {
        if (msg.typ == 'sys' && msg.act == 'aut' && msg.res == 'suc') {
            // hurray, we're connected and authenticated :-D
        }
    })
})