ES Documentation
手册
API
手册
API
简体中文

规范

请求路径

规则

请求路径的格式遵循 /main-api/{version}/{moduleName}/{entityName}/{methodName}。

TIP
  • {version} 为 API 版本号，目前为 v1。
  • {moduleName}：模块名称。
  • {entityName}：实体名称。
  • {methodName}：方法名称。

示例

例如，/main-api/v1/device/talk-server/updateById 就是一个符合规则的请求路径示例。

请求结构 (Api request)

鉴权方式

可以通过登录接口获取 authorization。在需要鉴权的接口中，有两种方式添加鉴权信息：一是在 HTTP 请求头中添加 Authorization 值；二是在 URL 中添加 Authorization 参数。以下是示例代码：

HTTP 请求头中添加中添加 Authorization 值
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}
在 URL 中添加 Authorization 参数
1`/system-api/user-center/user/logind?Authorization=${loginUserStore.authorization}`

规则

请求结构需符合 OpenAPI 3.0 规范。

示例

HTTP: request body application/json
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}

响应结构 (Api response)

规则

  • status: 响应状态码，其默认值为 200，该状态码能够直观地反映出请求响应的大致情况。
    • : 成功执行请求，没有发生任何错误。
    • : 对象验证失败：请求参数缺失、长度或格式不符等校验未通过，具体原因见 error 字段。
    • : 身份验证失败：凭据错误、令牌无效或过期、缺少认证信息。
    • : 拒绝访问：已认证但无权访问目标资源（权限不足）。
    • : 业务逻辑验证失败：请求格式正确但业务条件不满足（如目标数据不存在），具体原因见 error 字段。
    • : 服务器内部错误：界面只显示 System Error，详细错误信息记录在服务端日志。
    • : 消息转换失败：请求体无法解析为目标对象或响应体序列化失败（数据格式不匹配）。
    • : 控制器参数校验失败：表单字段缺失、超长或格式不符，具体原因见 error 字段。
  • error: 错误描述信息，此为可选字段，仅在出现异常情况时才会返回相关内容，以便使用者清晰知晓出现问题的具体缘由。
  • timestamp: 响应时间戳
  • path: 请求路径
  • extraData: 扩展数据, Map<String, Object> 类型，用于存储额外的、非标准的数据
  • data: 响应数据，此为可选字段，仅在实际有数据需要返回时，才会呈现相应的内容。

示例

HTTP: response application/json
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}
目录