Web API 接口设计规范
协议
API 与客户端通讯协议主要包含 http 和 https,建议使用https 确保交互数据的传输安全。
域名
主要包含两种形式:
主域名:https://api.example.com
子目录:https://example.org/api/
版本控制
版本控制主要用于 App、微信小程序、软件客户端等与系统不可同时实时更新的情况,来满足需要兼容旧版本的场景。
采用多版本并存,增量发布的方式。
版本号:v{n} n代表版本号,分为整形和浮点型
整型:大功能版本发布形式;具有当前版本状态下的所有API接口,例如:v1,v2
浮点型:为小版本号,只具备补充 api 的功能,其他 api 都默认调用对应大版本号的 api 例如:v1.1 v2.2
将版本号放入 URL 中:
https://api.example.com/v{n}/
这种方法比较方便和直观,版本号主要以整型为主。
将版本号放在请求头(Request Headers)中
headers:{
version: 'v{n}'
...
}
版本号可使用整型、浮点型等
路径规则
路径又称 “终点”(endpoint),表示 API 的具体网址。
在 RESTful 架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的 “集合”(collection),所以 API 中的名词也应该使用复数。
举例来说,有一个 API 提供动物园(zoo)的信息,还包括各种动物和雇员的信息,则它的路径应该设计成下面这样。
https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees
请求方式
对于资源的具体操作类型,由 HTTP 动词表示。
常用的 HTTP 动词有下面四个(括号里是对应的 SQL 命令)。
GET(SELECT) //从服务器取出资源(一项或多项)。
POST(CREATE)//在服务器新建一个资源。
PUT(UPDATE) //在服务器更新资源(客户端提供改变后的完整资源)。
DELETE(DELETE)//从服务器删除资源。
例如:
GET /product //列出所有商品
POST /product //新建一个商品
GET /product/ID //获取某个指定商品的信息
PUT /product/ID //更新某个指定商品的信息
DELETE /product/ID //删除某个商品
GET /product/ID/purchase //列出某个指定商品的所有投资者
GET /product/ID/purchase/ID //获取某个指定商品的指定投资者信息
传入参数
传入参数分为 3 中类型
- 地址栏参数
restful 地址栏参数 /api/v1/product/122
// 122 为产品编号,获取产品为 122 的信息
get方式的查询字串,此种方式主要用于过滤查询,如下:
?limit=10 //指定返回记录的数量
?offset=10 //指定返回记录的开始位置。
?page=2&per_page=100 //指定第几页,以及每页的记录数。
?sortby=name&order=asc //指定返回结果按照哪个属性排序,以及排序顺序。
?producy_type=1 //指定筛选条件
- 请求 body 数据
主要用于提交新建数据等 - 请求头
用于存放请求格式信息、版本号、token 密钥、语言等信息。
{
Accept: 'application/json', //json格式
version: 'v1.0' //版本号
Authorization: 'Bearer {access_token}', //认证token
language: 'zh' //语言
}
返回格式
默认返回格式:
{
errorCode: 0, //状态码
message: 'ok', //提示信息
data: {
} //主体数据
}
使用 json 格式作为响应格式,状态码分为两种:
- statusCode: 系统状态码,用于处理响应状态,与 http 状态码保持一致,如:200 表示请求成功,500 表示服务器错误。
- code:业务状态码,用于处理业务状态,一般 0 标识正常,可根据需求自行设计错误码对照表,参考微信官方文档,如下
https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Global_Return_Code.html - message 提示信息要进行统一,根据不同情况
- data可以是JSON对象也可以是JSON数组,具体看业务需求。但要保证在不同情况下data的类型是一致的。
- 正常的后端接口响应,HTTP Status Code 默认返回 200,只有在下列情况时接口才会出现非 200 的情况:
当服务端鉴权失败时返回 HTTP Status Code 401
中间环节三方软件返回的标准错误码,例如 Nginx 返回的 5** 错误码 - 当接口 HTTP Status Code 非 200 时,返回的结构如下:
{
"errorCode": {
通用处理结果代码},
"data": null,
"message": "对应的错误消息"
}
- 数组格式如下
{
"code": 0,
"message": "SUCCESS",
"data": [
{
"id":1,
"name":"小王",
"age":20
},
{
"id": 2,
"name": "小李",
"age": 30
}
]
}
{
"code": 0,
"message": "SUCCESS",
"data": [
"小李",
"小王"
]
}
- 分页列表格式
{
"code": 0,
"message": "SUCCESS",
"data": {
"pageSize": 10,
"page": 12,
"total": 118,
"list": [
{
"id": 1,
"name": "小王",
"age": 10
},
{
"id": 1,
"name": "小王",
"age": 10
}
]
}
}