Standards#

Request topic#

Rules#

The request topic follows the format server/{serverNo}/{serviceName}/{version}/{topicSuffix}, where:

Example#

For example, server/center-server/iot/v1/list-online-status is a valid request topic.

Request structure (Api request)#

Rules#

• sub: Sub-topic, used only in relatively complex bidirectional communication scenarios; leave it empty otherwise. It distinguishes different businesses that share the same topic.
• id: Session ID, a unique identifier used to distinguish different clients; an MQTT client ID must be provided. The MQTT client ID generation rules are as follows:
  • Web client: user,{username},web,{sessionId}
  • App client: user,{username},app,{sessionId}
  • Device management service: device,{deviceNo},iot,{sessionId}
  • Device WebRTC service: device,{deviceNo},webrtc,{sessionId}
  • Collection server file service: server,{serverNo},file,{sessionId}
  • Center or collection server data service: server,{serverNo},iot,{sessionId}
  • Center server device service: server,{serverNo},device,{sessionId}
• reply: MQTT response message topic path; optional, set only when response data is needed. The responder returns response data via this topic. This design makes third-party integration easier — third-party systems can subscribe to topics according to their own conventions and use their own topic-definition rules. This field exists for compatibility with clients that do not support MQTT 5.0 features (corresponds to Response Topic in MQTT 5.0).
• replyNumberMax: Maximum reply count; optional. Set only when response data must be returned more than once. The server restricts the range to 1–10; if empty, the default is 1.
• replyInterval: Reply interval (seconds); optional. Set only when response data must be returned more than once. The server restricts the range to 1–10 seconds; if empty, the default is 1 second.
• token: Authentication token, used only for HTTP interface permission checks; the MQTT pipeline does not read this field (MQTT access is authorized via broker accounts / ACL).
• params: Parameters; optional, set only when parameters need to be passed.

Example#

1{
2  "id": "user,admin,web,session-id-xxx",
3  "token": "token-xxx",
4  "reply": "user/admin/web/session-id-xxx/rx/resp/server/center-server/iot/v1/list-online-status",
5  "params": {
6    "mqttClientIdPrefixes": [
7      "user,admin,web",
8      "user,admin,app",
9      "device,asr-1,webrtc",
10      "device,asr-1,iot",
11      "server,center,iot",
12      "server,center,file"
13    ]
14  }
15}

Response topic#

Rules#

Specified by the reply field in the request structure; if the field is empty, no reply is sent.

Example#

For example, user/admin/web/session-id-xxx/rx/resp/server/center-server/iot/v1/list-online-status. Third-party systems can subscribe to topics according to their own conventions and use their own topic-definition rules.

Response structure (Api response)#

Rules#

• id: Session ID, a unique identifier used to distinguish different clients. In response envelopes the id is the server's outbound MQTT client ID (a fixed three-segment form, e.g. server,center-server-1,iot in the sample environment), which differs from the caller-supplied id.
• reply: MQTT response message topic path; optional, set only when response data is needed. The responder returns response data via this topic. This design makes third-party integration easier — third-party systems can subscribe to topics according to their own conventions and use their own topic-definition rules. This field exists for compatibility with clients that do not support MQTT 5.0 features (corresponds to Response Topic in MQTT 5.0).
• status: Response status code; the default is 200. It gives a quick indication of the overall result of the request.
  • 200: The request was executed successfully without any errors.
  • 400: Object validation failed: request parameters missing, over-length, or malformed; see the error field for details.
  • 401: Authentication failed: wrong credentials, invalid or expired token, or missing authentication information.
  • 403: Access denied: authenticated but lacking permission for the target resource.
  • 422: Business logic validation failed: the request is well-formed but a business condition is not met (e.g., target data not found); see the error field for details.
  • 500: Internal server error: the UI only shows "System Error"; details are recorded in server-side logs.
  • 1000: Message conversion failed: the request body cannot be parsed into the target object or the response body cannot be serialized (data format mismatch).
  • 1001: Controller parameter validation failed: form fields missing, over-length, or malformed; see the error field for details.
• error: Error description; optional, returned only when an exception occurs, so the caller can clearly understand the specific cause.
• data: Response data; optional, present only when there is data to return.
• replyNumber: Reply count, corresponding to replyNumberMax in the request structure, indicating the number of replies for this request.

Example#

1{
2  "id": "server,center-server-1,iot",
3  "status": 200,
4  "data": [
5    {
6      "mqttClientIdPrefix": "user,admin,web",
7      "onlineStatus": true
8    }
9  ]
10}