API接口规范

协议:API与用户的通信协议,总是使用HTTPs协议。

一、域名规范

应该尽量将API部署在专用域名之下。
https://api.example.com

如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下。
https://example.org/api/

二、HTTP请求方式

GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)
PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)
DELETE(DELETE):从服务器删除资源。

三、过滤信息

?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?producy_type=1:指定筛选条件

四、返回码说明:

返回格式:json

200 OK - [GET]:请求成功
201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]:用户删除数据成功。
400   客户端请求时所提交的参数不正确(通常为客户端的问题)
401   未提供accessToken(即未登录)
403   权限不足(已登录,但不具有访问该资源的权限)
404   找不到该资源(通常为请求的地址不正确)
406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
500   服务发生错误(通常为服务端的问题)

公共返回码
成功类:
10001 保存成功
10002 删除成功
10003 操作成功
10004 审核成功

失败类
20001 操作失败
20002 代码已存在
30001 无权限
30002 系统错误
30003 参数错误
30004 路径不存在

五、错误处理

errorcode:错误代码
errortext:错误文本说明
error:是否错误,0正确,1错误

六、接口分类

查询类例子:

GET /product:列出所有商品
GET /product/ID:获取某个指定商品的信息
GET /product/ID/purchase :列出某个指定商品的所有投资者
GET /product/ID/purchase/ID:获取某个指定商品的指定投资者信息

操作类例子:

POST /product:新建一个商品
DELETE /product/ID:删除某个商品   
PUT /product/ID:更新某个指定商品的信息
PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息) 

七、返回数据

接口返回模板:

{
status:0,
data:{}||[],
msg:’’
}

status: 接口的执行的状态

=0表示成功
<0 表示有异常="" 

Data:接口的主数据,可以根据实际返回数组或JSON对象

Msg

当status!=0 都应该有错误信息

八、API接口设计原则

1、API 命名应该采用约定俗成的方式,保持简洁明了;
2、考虑到系统迭代和兼容性需求,API 中应该引入版本规则;
3、优雅的设计条件过滤、排序、搜索等传入参数形式;
4、合理设计返回数据的形式,格式和考虑启用压缩(GZIP);数据返回结果建议使用JSON;
5、根据不同的 API 操作,设置合适的 HTTP 状态码和必要的出错信息;
6、使用 Token 机制设计鉴权和验证系统(Authorization and Authentication)
7、如何实现数据的分页返回;
8、如何处理有关联资源的返回数据;
9、考虑启用 HTTP 缓存机制,以改善网络通信效率;
10、无状态通信的会话状态应该全部由客户端负责维护;
11、分层系统通过限制组件的行为(即每个组件只能看到与其交互的紧邻层),将架构分解为若干等级的接口层;
限制 API 调用频次(Rate limiting);
12、尽可能的使用 HTTPS,涉及用户验证的 API 一定要强制启用 HTTPS。

214 total views, 2 views today

Revisions

No comments yet.

发表评论