System Topics

The shiftr.io platform offers various system topics that allow clients to inspect the network and obtain valuable metadata.

Please note that system topics are not in their final state and may receive minor changes.

Events

A MQTT subscription to $events will put the client in a special mode where all interactions with the network are received as JSON encoded objects under the $events topic. A subscription to $events will temporarily shadow other subscriptions as all messages are received as events.

Connected

{
  "id": "5bf2c2147b0a6769f6d287c4",
  "type": "connected",
  "connection": {
    "id": "5bda2ea6e334550009ab27f8",
    "name": "test",
    "read_only": false
  }
}

Subscribed

{
  "id": "5bf2c2147b0a6769f6d287c6",
  "type": "subscribed",
  "subscription": {
    "topic": "foo",
    "qos": 1,
    "root_slash": false,
    "connection_id": "5bda2ea6e334550009ab27f8"
  }
}

Published

{
  "id": "5bf2c2147b0a6769f6d287c8",
  "type": "published",
  "message": {
    "topic": "foo",
    "payload": "Y29vbA==",
    "qos": 0,
    "retained": false,
    "connection_id": "5bda2ea6e334550009ab27f8"
  }
}

Unsubscribed

{
  "id": "5bf2c2147b0a6769f6d287ca",
  "type": "unsubscribed",
  "unsubscription": {
    "topic": "foo",
    "connection_id": "5bda2ea6e334550009ab27f8"
  }
}

Disconnected

{
  "id": "5bf2c2147b0a6769f6d287cc",
  "type": "disconnected",
  "disconnection": {
    "id": "5bda2ea6e334550009ab27f8",
    "name": "test"
  }
}

Errored

{
  "id": "5bf2c2147b0a6769f6d287ce",
  "type": "errored",
  "error": {
    "code": "invalid-topic",
    "topic": "foo/+",
    "connection_id": "5bda2eeee334550009ab85b0"
  }
}

Triggered

{
  "id": "5bf2c2147b0a6769f6d287d0",
  "type": "triggered",
  "action": {
    "type": "close",
    "target_id": "5bda2cb9e334550009a88e57",
    "connection_id": "5bda2eeee334550009ab85b0"
  }
}

Actions

A HTTP POST request or a MQTT publication to $action with a JSON encoded object will instruct the broker to perform various actions.

Close

{
  "type": "close",
  "target_id": "5bda2cb9e334550009a88e57"
}

Info

A HTTP GET request or a MQTT subscription to $info will return a JSON encoded object that includes various information about the current state of the network.

{
  "topics": ["foo", "bar/baz"],
  "connections": [
    {
      "id": "5bda2cb9e334550009a88e57",
      "name": "test",
      "read_only": false
    }
  ],
  "subscriptions": [
    {
      "topic": "foo",
      "qos": 1,
      "root_slash": false,
      "connection_id": "5bda2cb9e334550009a88e57"
    }
  ]
}

Rate

A HTTP GET request or a MQTT subscription to $rate will return a JSON encoded object that includes information about the current rate limit:

{
  "scope": "user",
  "limit": 1500,
  "remaining": 1499,
  "period": 60,
  "retry_in": 0,
  "reset_in": 1
}