RESTful API设计规范学习
2020-02-20
在RESTful设计规范里，第一个接口被认为是一个资源请求
路径设计注意事项
- 资源名使用复数
- 资源名使用名词
- 路径内不带特殊字符
- 避免多级URL
URL
URL表示资源，资源一般对应服务器端领域模型中的实体类
URL规范
- 不用大写
- 用中杠- 不用下杠_
- 参数列表要encode
新增资源
使用POST定义，数据通过RequestBody方式进行传递
示例：
删除资源
使用DELETE定义接口，删除单个资源，将资源的主键值通过路径方式传递给接口；删除多个资源时通过RequestBody方式传递数据。
示例：
批量删除 https://api.my.com/v1/users 单个删除 https://api.my.com/v1/users/{id}
更新资源
使用PUT定义接口。
示例：
https://api.my.com/v1/users/{id}
查询单个资源
使用GET定义接口。
示例：
https://api.my.com/v1/users/{id}https://api.my.com/v1/users?name={name}
分页查询资源
使用GET定义接口。
示例：
https://api.my.com/v1/users?page=1&size=20&name={name}
动作资源
使用POST定义接口。有动作性的修改某一个资源的元素内容，比如重置密码。
示例：
https://api.my.com/v1/users/{id}/actions/forget-password 其中用户唯一标识在请求路径中进行传递，修改后的密码通过RequestBody方式进行传递。
安全性和幂等性
- 安全性：不会改变资源状态，可以理解为只读的；
- 幂等性：执行1次和执行N次，对资源状态改变的效果是等价的
请求方式 | 安全性 | 幂等性 |
GET(SELECT) | √ | √ |
POST(CREATE) | × | × |
PUT(UPDATE) | × | √ |
DELETE(DELETE) | × | √ |
数据返回格式
请求方式 | response格式 |
GET | 单个对象、集合 |
POST | 新增成功的对象 |
PUT/PATCH | 更新成功的对象 |
DELETE | 空 |
json格式的约定
- 时间用长整形（毫秒数），客户端自己按需解析
- 不传null字段
版本号
版本号用于区分api接口的各个版本，比较流行的是接口路径、头信息两种方式。
**1. 接口路径方式 **
示例：
2. 头信息方式
可以将访问接口版本通过HttpHeader方式进行传递，在网关根据提取到的头信息进行控制转发，这种方式资源路径的展现形式不会因为版本的不同而变化。
版本头信息的Key可以根据自身情况进行定义，推荐使用Accpet形式。
状态码
在接口设计时我们需要通过HttpStatus请求的状态码来判断一个请求发送状态，本次请求是否有效，常见HttpStatus状态码如下所示：
状态码 | 说明 |
200 | 请求成功 |
201 | 新资源创建成功 |
204 | 没有任何内容返回 |
400 | 传递的参数格式不正确 |
401 | 没有权限访问 |
403 | 资源受保存 |
404 | 访问的路径不正确 |
405 | 访问方式不正确，GET请求使用POST方式访问 |
410 | 地址已经被转移，不可用 |
415 | 要求接口返回的格式不正确，比如：客户端需要JSON格式，接口返回的是XML |
429 | 客户端请求次数超过限额 |
500 | 访问的接口出现系统异常 |
503 | 服务不可用，服务一般处理维护状态 |
请求头
用于存放请求格式信息、版本号、token密钥、语言等信息
{
Accept:'application/json',
version:'v1.0',
Authorization:'Bearer {access_token}',
language:'zh'
}
