Standards#

Request path#

Rules#

The request path follows the format /main-api/{version}/{moduleName}/{entityName}/{methodName}.

Example#

For example, /main-api/v1/device/talk-server/updateById is a valid request path.

Request structure (Api request)#

Authentication#

You can obtain authorization via the login API. For endpoints that require authentication, there are two ways to provide authentication information: add the Authorization value to the HTTP request header, or add the Authorization parameter to the URL. Example code:

1{
2    headers: {
3        Accept: 'application/json;charset=UTF-8',
4        'Content-Type': 'application/json',
5        'Authorization': `Bearer ${loginUserStore.authorization}`
6    },
7    credentials: 'include',
8    mode: 'cors',
9    cache: 'no-cache'
10}

1`/system-api/user-center/user/logind?Authorization=${loginUserStore.authorization}`

Rules#

The request structure must conform to the OpenAPI 3.0 specification.

Example#

1{
2  "deviceId": "string",
3  "deviceModelId": "string",
4  "orgId": "string",
5  "deviceNo": "string",
6  "name": "string",
7  "intro": "string",
8  "state": "string",
9  "installedLocation": "string",
10  "installedTime": "2025-06-10T09:36:05.709Z",
11  "childTableName": "string",
12  "revision": 0,
13  "tenantId": "string",
14  "janusNo": "string",
15  "stunServer": "string",
16  "turnServer": "string",
17  "turnUsername": "string",
18  "turnCredential": "string",
19  "sourceUsername": "string",
20  "sourceTenantId": "string",
21  "sourceDeviceId": "string",
22  "talkServerId": "string",
23  "domainName": "string",
24  "port": 0
25}

Response structure (Api response)#

Rules#

• 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.
• timestamp: Response timestamp.
• path: Request path.
• extraData: Extended data, of type Map<String, Object>, used to store additional, non-standard data.
• data: Response data; optional, present only when there is data to return.

Example#

1{
2  "timestamp": 0,
3  "status": 200,
4  "path": "/system-api/user-center/user/logind",
5  "extraData": {
6    "additionalProp1": {},
7    "additionalProp2": {},
8    "additionalProp3": {}
9  },
10  "data": null
11}