50 lines
1.1 KiB
Markdown
50 lines
1.1 KiB
Markdown
# api-desgin
|
|
|
|
## URL spec
|
|
|
|
基础路径由关键记录加版本号组成，如 `/api` + `/${version}`
|
|
```
|
|
/api/${version}
|
|
```
|
|
|
|
通常版本从 `1` 开始，第一个版本为 `v1`，下一个版本则为 `v2` ...
|
|
|
|
所以版本的基础路径一般如下：
|
|
```
|
|
/api/v1
|
|
/api/v2
|
|
```
|
|
|
|
所有的接口都与资源相关，所以需要定义相关的资源及其复数形式，常见的资源地址如下：
|
|
|
|
```
|
|
/api/v1/${resources}
|
|
|
|
/api/v1/${resources}/${resource_id}
|
|
|
|
/api/v1/${resources}/_/actions/${action}
|
|
|
|
/api/v1/${resources}/${resource_id}/actions/${action}
|
|
```
|
|
|
|
## id spec
|
|
|
|
保留的 id 为单字母，所以一个正常的 id 必须大于一个字母，建立使用带前缀的方式进行命名
|
|
|
|
单字线保留表
|
|
|
|
| 保留字母 | 备注 |
|
|
| ---- | ---- |
|
|
| `_` | 用于表示不与任何一个 id 绑定 |
|
|
|
|
|
|
常见前缀及命名方法：
|
|
|
|
| 命名方法 | 示例 |
|
|
| ---- | ---- |
|
|
| 小写 + 前缀 + 数字序列 | user_123456 |
|
|
| 小写 + 前缀 + 16字节随机数(base32) | user_z3ymhvyxtzvxjyewrsqf5ozgya |
|
|
| 大写 + 前缀 + 16字节随机数(base58) | USERVQ5sS43wpZJycVgPPhwFwh |
|
|
|
|
|