安全
- 总是使用 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 同步更新
- 文档格式的三个部分:请求方式、路径;参数名称、参数类型、参数注解;完整的响应示例