Topic structure

Topic structure

A topic in the HTTP device API is the last part of the URL. For reference, the endpoint for sending messages is https://api.gridsense.cloud/http/<topic>

In order for messages to be published to a specific channel and be associated with it, topics must begin with a special value:

m/<organization>/c/<channel>

where <organization> and <channel> are the IDs of the organization and channel respectively. Alternatively, the routes of the organization and channel can be used instead.

This serves as the bare minimum value that is accepted as a topic, which ensures the hierarchy of organizations and channels is respected, and as a result, that publishing to and reading from channels works as expected and that the dashboards you build and the widgets used in them accurately read and display data.

Subtopics

The main topic can be built upon to construct more granular topics, also referred to as subtopics.

Subtopics when sending messages (the POST endpoint)

To publish to a subtopic, simply append the subtopic to the end of the main topic:

m/<organization>/c/<channel>/subtopic

Subtopics can also be nested, with a forward-slash / separating every two levels:

m/<organization>/c/<channel>/subtopic/nested_subtopic[/...]

Adjacent forward-slashes are discarded to flatten the topic. This means the following two topics are equivalent:

m/<organization>/c/<channel>/subtopic/nested_subtopic////another_subtopic
m/<organization>/c/<channel>/subtopic/nested_subtopic/another_subtopic

Subtopics when getting messages (the GET endpoint)

If you would like to get messages published under a certain subtopic, you must pass this subtopic as a URL query parameter. For example:

# Read data from a specific channel and subtopic
curl 'https://api.gridsense.cloud/v1/readers/<organization>/channels/<channel>/messages?subtopic=mySubtopic&limit=10&offset=0' \
  --header 'Authorization: Client <device secret>'

Notice that the subtopic was not appended after m/<organization>/c/<channel> as is done in the POST endpoint, but rather as a URL query parameter.