一、版本号
将API的版本号放入URL。版本号以’v‘开头，比如'v1'。
https://api.leslie.com/v1/*
二、路径
- URL的命名必须全部小写
- URL中资源（resource）的命名必须是名词，且必须是复数
- URL中不能出现
-，必须用下划线_ - URL必须易读
- URL不能暴露服务器架构
例：
查询所有用户 GET /v1/users
查询指定用户 GET /v1/users/:id
新增一个用户 POST /v1/users
更新指定用户 PUT /v1/users/:id
删除指定用户 DELETE /v1/users/:id
查询所有用户角色 GET /v1/user_roles
查询指定的用户角色 GET /v1/user_roles/:role
三、筛选
1、过滤
/v1/users?gender=male
2、指定数量
/v1/users?limit=10
3、指定位置
/v1/users?offset=20
4、排序
/v1/users?sort=+age
/v1/useer?sort=-age
5、分页
/v1/users?page=1&per_page=10
6、字段选择
/v1/users?fields=name;age;gender
四、文件类接口
1、统一提供单文件上传接口（v1/files），支持所有文件类型的上传
// 请求（FormData格式）
{
file: File
}
// 响应
{
code: 200,
status: 'success',
data: {
id: '1',
type: 'image',
url: '/xxx/1.jpg',
name: '1.jpg'
}
}
2、统一提供多文件上传接口（v1/multiple_files），支持所有文件类型的上传
// 请求（FormData格式）
{
files: [File, File]
}
// 响应
{
code: 200,
status: 'success',
data: {
files: [
{
id: '2',
type: 'pdf',
url: '/xxx/2.pdf',
name: '2.pdf'
},
{
id: '3',
type: 'pdf',
url: '/xxx/3.pdf',
name: '3.pdf'
}
]
}
}
五、图表类接口
1、曲线图、柱状图
{
code: 200,
status: 'success',
data: {
xAxis: ['24/05/08', '24/05/09', '24/05/10'],
series: [
{
name: '珠海',
data: [100, 108, 106]
},
{
name: '广州',
data: [108, 106, 100]
}
]
}
}
2、饼图
{
code: 200,
status: 'success',
data: {
series: [
{
name: '在线用户',
value: 999999999
},
{
name: '离线用户',
value: 111111111
}
]
}
}
六、返回统一的数据格式
RESTful规范中的请求应该返回统一的数据格式。
- code：HTTP响应的状态码；
- status：HTTP响应状态码在500-599之间为“fail”，在400-499之间为“error”，其它一般为“success”（当status的值为“fail”或“error”时，需添加message字段，用于显示错误信息。）；
- data：当请求成功的时候，返回数据信息。当状态值为fail或error时，data仅包含错误原因或异常信息等。
返回成功的响应格式
// 不分页
{
code: 200,
status: 'success',
data: {}
}
// 分页
{
code: 200,
status: 'success',
data: {
list: [],
total: 0
}
}
// 创建成功只返回id
{
code: 200,
status: 'success',
data: {
id: '1'
}
}
返回失败的响应格式
{
code: 401,
status: 'error',
message: '没有权限',
data: null
}
参考：
