Topic Management

This guide will explain the anatomy of “topics” that are used to make subscriptions and publish messages.

When a client publishes a message to shiftr.io, the message is identified with a “topic”. The topic acts as an identifier or category tag, similar to Twitters hashtags. When the message is received by the broker, it will match the topic of the incoming message with topics that have been previously subscribed by other clients. If a clients subscription matches the topic, the broker will send the message to the client.

In publish & subscribe tongue, we will speak therefore of publishing a message to a topic and making a subscription on a topic.

Anatomy

A topic consists of an arbitrary amount of “segments”, which are separated by a slash /:

1
2
3
theromstat/temperature
sensors/1/settings/frequency
get/position/x

With this separation of segments, multiple topics with similar segments can be represented in a tree:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
my-house
  first-floor
    door
      locked
      open-since
    thermostate
      temperature
      last-measure
  basement
    washmashine
      active
      remaining-time
    thermostate
      temperature
      last-measure

From that tree we can get again single topics, to which we can publish messages:

1
2
PUBLISH my-house/first-floor/door/open-since | 08:34
PUBLISH my-house/basement/washmashine/active | true

It is also possible to publish messages to parent nodes:

1
2
PUBLISH my-house/first-floor | power-on-lights
PUBLISH my-house/basement/washmashine | off

There are no rules about how this tree has to be structured, however there are some best practices we will take a look at later.

URL similarity

Topics are heavily inspired by the URL used for websites. Topics as well as URLs share the idea of giving the user freedom about how information (messages) is/are located in his system. Many concepts, like REST also apply to topics and can be used the same way to structure a complex system.

Subscriptions

In order to receive messages on other clients, the receiving client needs to make a subscription. Such a subscription can be made on any topic as described above:

1
2
SUBSCRIBE my-house/first-floor/thermostate/temperature
SUBSCRIBE my-house/basement

The client will now receive any message published to the topics he has subscribed.

Wildcards

To support applications that deal with complex systems and many topics, subscriptions can also include wildcards. The wildcard + can be used to match any segments at that position in the tree, whereas the # will match any following segments:

1
2
SUBSCRIBE my-house/+/thermostate/temperature
SUBSCRIBE my-house/basement/#

The alternative notation of * as a single level wildcard gets automatically converted to +.

Best Practices

Resources

A good starting practice is the “resource based” structure, which borrows the layout from the REST concept for URLs.

By using that layout, one can easily match certain types of resources using wildcards:

1
2
PUBLISH rooms/1/light-sensors/13/activated | true
SUBSCRIBE rooms/1/light-sensors/+/activated