安全
- 总是使用 TLS，非 TLS 不重定向，直接返回调用错误 403
- 无状态认证机制使用 JWT
URI 的定义
URI 是对一个资源的指向，同一个资源必须使用同一个 URI，不同的资源使用不同的 URI。资源的处理使用动词，GET（查询）、POST（创建）、PUT（全局更新）、PATCH（局部更新）、DELETE（删除）。
| 请求方式动词 | URI | 注解 |
|---|---|---|
| GET | /users | 显示所有用户列表的页面 |
| GET | /users/{id} | 显示用户个人信息的页面 |
| GET | /users/create | 创建用户的页面 |
| POST | /users | 创建用户 |
| GET | /users/{id}/edit | 编辑用户个人资料的页面 |
| PATCH | /users/{id} | 更新用户 |
| DELETE | /users/{id} | 删除用户 |
- 使用复数来命名资源，即使资源绝对只有一个
- 路径、参数均要小写
- 路径要为名词，不要为动词
- 路径如果需要多个单词，可以用减号隔开
- 路径中的 /，用于表示资源之间的层次关系
- 参数名称如果需要多个单词，可以用下划线隔开
- URI 末尾不要包含斜杠
- URI 中不包含文件的扩展名
查询参数
排序
字段前缀”-“表示降序
?sort=-create_time,id过滤
不返回 content,keywords 信息
?fields=content,keywords版本
三种方式
- HTTP Accepts 头
- URL
- URL 主版本、HTTP 次版本
Request Headers
Content-Type 为 application/json，否则响应返回 415 Unsupported Media Type
状态码
客户端请求错误使用 400 系列状态码，服务端响应错误使用 500 系列状态码。
| 状态码 | 注解 |
|---|---|
| 200 | 请求资源成功 |
| 201 | 同步处理资源的新建或修改成功，返回包含新资源地址的 Location 头 |
| 202 | 资源的新建或修改进入异步 |
| 204 | 不返回响应主体的成功请求的响应，例如，资源删除成功 |
| 206 | 返回了部分资源 |
| 400 | 请求格式、参数缺失或者错误 |
| 401 | 没有权限 |
| 403 | 访问被禁止 |
| 404 | 资源不存在 |
| 405 | 所请求的 HTTP 方法不允许当前认证用户访问 |
| 406 | 请求的数据格式不存在 |
| 410 | 资源被永久删除 |
| 415 | 请求的媒体类型错误 |
| 422 | 请求理解成功，但是参数验证错误 |
| 429 | 请求频率超限 |
| 500 | 服务器内部错误 |
响应主体
- 全局唯一的小写的 8-4-4-4-12 格式的 UUID，如果嵌套资源，嵌套的资源内依然需要具备一个这样的 UUUID
- 资源的创建时间
- 资源的最后更新时间
- 下一步可用的 URL，客户端不需要关心
- 修改或者创建后，尽量完整的资源详细数据
错误
- 唯一的错误码
- 错误信息
- 详细的细节描述
自定义 Headers
关于调用频率的一个例子：
X-Rate-Limit-Limit：当前时间段内允许的最多请求次数
X-Rate-Limit-Remaining：当前时间段内剩余的请求次数
X-Rate-Limit-Reset：还有多少秒，请求次数限制会被重置目前大部分使用“X-”前缀来区分自定义与非自定义的 HTTP 头，RFC 6848 已经开始废弃这种做法，但目前依然可用。
缓存
- ETag
- Last-Modified
API WIKI 文档要点
- API 文档要与 API 同步更新
- 文档格式的三个部分：请求方式、路径；参数名称、参数类型、参数注解；完整的响应示例
