接口URL规范#
结尾包含语义#
语义化URL的好处在于可一眼看出URL的功能。上图提供了URL的前缀，我们通过前传加上语义结尾的URL即可得到完整的URL地址。业务化语义结尾规范#
比如我们现 在要绑定设备，我们通过上述图中理解可以得到绑定设备属于设备规范，绑定设备我们的语义结尾是 bind, 那么完整的URL地址应该是 /api/v2/userctx/user/child/device/bind固定化语义结尾规范#
语义化并不能代表全部的场景，有一些场景实际上只是增删改查，我们也对这些场景做了语义化规范，这些场景我们叫做固定化语义。固定化语义存在基本的关键字 get update create delete truncate, 它们之间都有存在的意义。| 固定化语义 | 请求模式 | 参数形式 | 例子 | 解释 |
|---|
| delete | GET | query | /api/v2/userctx/user/child/delete | 支持删除条件 |
| truncate | GET | - | /api/v2/userctx/user/child/truncate | 不支持指定参数，如果需要指定条件请使用 delete 固定化语义。 |
| get | GET | query | /api/v2/userctx/user/child/get | 支持过滤条件 |
| update | POST | body | /api/v2/userctx/user/child/update | |
| create | POST | body | /api/v2/userctx/user/child/create | |
请在有如下Header数据时务必携带后再请求，后续方便定位问题和调试。| Key | 示例值 | 说明 |
|---|
| X-System | IOS ANDROID RTOS | 请求时的系统 |
| X-System-Version | IOS 18 | 请求时的系统版本 |
| X-Software-Version | v1.0.0 | APP版本 |
| X-Manufacturer | XIAOMI, Apple | 手机型号 |
| X-Time-Zone | Asia/Shanghai | 时区 |
| X-Timestamp | 1726215903000 | 请求时的时间戳 请精确到毫秒 |
| X-Request-Id | 51c6c683-511b-4d93-bbd6-1b1e8ce7b7d8 | 请求的唯一Id |
| Localization | zh-Hans-CN | 语言 |
手表设备#
| Key | 示例值 | 说明 |
|---|
| X-Status-Battery | 60 | 信号 |
| X-Status-Signal | 1 | 最大信号 |
| X-Status-Signal-Max | 5 | 电量 |
| X-Step | 1000 | 步数 |
原生协议#
HTTP 提供了一些很好用的 Header可使用。| Key | 示例值 |
|---|
| Authorization | Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1aWQiOiJ... |
| Accept-Language | fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 查看文档 |
Response#
我们这里使用了 Http 自带的 StatusCode, 具体的状态码信息请阅读： HTTP Status ，这里详细解释了状态码的作用。{
"status": 500,
"path": "/api/v2/userctx/user/child/create",
"message": "手机号已存在",
"reason": "Internal Server Error",
"requestId": "deee3f26-9bff-4dd4-a053-f7b69faab6bb",
"error": "BusinessException{code=500, message='手机号已存在', reason='PHONE_NUMBER_EXIST'}"
}
有一些接口去操作数据（比如修改服务器某个资源）不会返回结果，客户端可无需关注 Response，只要 HttpStatus：200 即可
原来的 JSON#
{
"code": 200,
"message": "ok",
"data": {
"text": "hello world !"
}
}
新的 JSON#
{
"text": "hello world !"
}
