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; left empty otherwise. It distinguishes different business operations when the topic is the same.
• id: Session ID, a unique identifier used to distinguish different clients. An MQTT client ID must be supplied. 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. This is an optional field, set only when response data is required; the responder returns the response data via this topic. This design eases integration for third-party systems, which may subscribe to topics according to their own conventions and use their own topic definitions. This field exists to support clients that lack MQTT 5.0 features (corresponding to Response Topic in MQTT 5.0).
• replyNumberMax: Maximum number of replies. This is an optional field, 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). This is an optional field, 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 specifically to verify interface permissions and ensure legitimate, secure use of the interface.
• params: Request parameters. This is an optional field, 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 that 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. A third-party system may subscribe to topics according to its own conventions and use its own topic definitions.

Response structure (Api response)#

Rules#

• sub: Sub-topic, used only in relatively complex bidirectional communication scenarios; left empty otherwise. It distinguishes different business operations when the topic is the same.
• id: Session ID, a unique identifier used to distinguish different clients. An MQTT client ID must be supplied. 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}
  • Center or collection server data service: server,{serverNo},iot,{sessionId}
  • Center server device service: server,{serverNo},device,{sessionId}
  • Collection server file service: server,{serverNo},file,{sessionId}
• reply: MQTT response message topic path. This is an optional field, set only when response data is required; the responder returns the response data via this topic. This design eases integration for third-party systems, which may subscribe to topics according to their own conventions and use their own topic definitions. This field exists to support clients that lack MQTT 5.0 features (corresponding 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: Number of replies, corresponding to replyNumberMax in the request structure; it indicates how many replies were made for this request.

Example#

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