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.
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.
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.
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.
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
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