Skip to main content

"describeTopics" (jsonAction)

JSON MQ "describeTopics" action returns info about MQTT topics

The "describeTopics" action returns all available information about specified MQTT topics.

Request examples

Minimal

{
  "api": "mq",
  "apiVersion": "1.0",
  "action": "describeTopics",
  "params": {
    "topics": [
      "test/topic1"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Minimal

{
  "result": {
    "data": [
      {
        "name": "test/topic1",
        "creationTime": "2024-02-01T23:47:45.814",
        "messageCount": 2,
        "lastMessageTime": "2024-02-01T23:47:51.716",
        "averageMessagesPerMinute": 0,
        "averageMessagesPerHour": 0,
        "averageMessagesPerDay": 0,
        "subscriberList": [
          {
            "topicExpression": "#",
            "connectionList": [
              {
                "connection": {
                  "clientId": "mqtt-explorer-001",
                  "ipaddress": "127.0.0.1",
                  "port": 35646,
                  "mqttProtocol": 4,
                  "keepAliveSeconds": 60,
                  "status": "Connected with clean flag = 1",
                  "connectionTime": "2024-01-31T17:31:19"
                },
                "qos": 0
              }
            ]
          },
          {
            "topicExpression": "test/#",
            "connectionList": [
              {
                "connection": {
                  "clientId": "NodeREDSecure",
                  "ipaddress": "127.0.0.1",
                  "port": 36115,
                  "mqttProtocol": 4,
                  "keepAliveSeconds": 60,
                  "status": "Connected with clean flag = 1",
                  "connectionTime": "2024-01-31T17:31:30"
                },
                "qos": 1
              }
            ]
          }
        ],
        "persistence": {
          "topic": "test/topic1",
          "sourcePayloadFormat": "json",
          "databaseConnectionString": "FAIRCOMS",
          "databaseUserName": "admin",
          "databaseName": "faircom",
          "tableName": "mqtt_msg_test_topic1",
          "ownerName": "admin",
          "threads": 1,
          "tableAutoTimeStamp": true,
          "tableAutoTimeStampIndex": true,
          "tableReplicationReady": true,
          "retentionPolicy": "autoPurge",
          "retentionUnit": "week",
          "retentionPeriod": 4,
          "storeAndForward": true,
          "maxDeliveryRatePerSecond": 0,
          "newSubscriberDeliveryMode": "default",
          "newSubscriberMaxDeliveredMessages": 0,
          "retrySeconds": 20,
          "outputPayloadField": "source_payload",
          "label": {
            "group": "group name",
            "name": "label name"
          }
        }
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

The describeTopics action returns all available information about specified MQTT topics

API actionsJSON MQ APIjsonActiondescribe topicdecribeTopics

"params"

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties. See System limits for a comprehensive look at property requirements and limitations.

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

topics

(optional) contains "topic" strings

[]

array



"result"

Properties summary

Table 2. "result" property summaries

Property

Description

Type

Limits (inclusive)

data

(optional) specifies an array or object that the server returns, such as records returned by a query. It is always included in a response but contains an empty array when no results are available.

It is an empty array when there are no results available

array

Its contents are determined by the action

sourcePayloadFormat

(optional) specifies the variant type format of the "source_payload" field

string

"json"
"xml"
"binary"
"jpeg"
"siemensUdt"
"utf8"


"sourcePayloadFormat"

The "sourcePayloadFormat" property is an optional string that defines the variant type format of the "source_payload" field. When omitted or set to null, it defaults to "binary".

  • This property is a string containing the following enumerated values:

    •  "binary"

    • "json"

    • "utf8"

    • "siemensUDT"

    • "jpeg"

    • "xml"

  • This property is a hint to the server about the format and type of the MQTT message payload.

  • This property does not cause server to validate the MQTT payload to see if it matches the type you set. The server stores the payload as is without validation. For example, if you set the type to "json", it does not stop the server from receiving and storing a non-JSON value or invalid JSON document in the source payload.

  • The FairCom Edge Explorer application may use the value of this property to determine the default way to display a topic's payload.

  • The transform engine may use the value of this property to help it transform the source payload.