接口规范

接口规范

一、Web API接口

1.1 什么是接口

​ 同通过网络，规定前后台信息交互规则的url连接，是前后台信息交互的媒介。

1.2 接口的组成

​ 1、url;

​ 2、请求方式：get、post、put、patch、delete;

​ 3、请求参数：json或xml格式的key-value类型数据；

​ 4、响应结果：json或者xml格式的数据

1.3 编写接口文档

​ 编写接口文档可以使用去哪网技术中心的一个开源可视化接口管理平台YApi。

​ http://yapi.demo.qunar.com/

​

二、Restful接口规范

​ REST全称是Representational State Transfer，中文意思是表述性状态转移,首次出现是在2000年Roy Fielding的博士论文中。

2.1 URL设计

​ 1、数据安全的保障

​ url连接一般采用https协议进行数据传输，可以提高数据交互过程中的安全性。

​ 2、接口特征的表现

​ 使用api关键字标识接口：https://api.lalala.com。

​ 注意：出现api，就代表该请求的url连接是为了完成前后台数据交互的。

​ 3、多版本数据共存

​ https://api.lalala.com/v1与https://api.lalala.com/v2，就是不同版本数据的体现。

​ 4、数据即资源

​ 接口即前后端交互的媒介，交互的数据即为资源。

​ https://api.lalala.com/users、https://api.lalala.com/data。

​ 推荐资源写复数形式，便于理解。

​ 连接中不要出现操作资源的动词，例如https://api.lalala.com/delete-user。

​ 没有明确资源的接口可以使用动词，或者东西就是接口的核心含义可以使用动词。

​ 例：https://api.lalala.com/login或https://api.lalala.com/content/search

2.2 响应状态码

1、正常响应

• 响应状态码2xx

  • 200：常规请求
  • 201：创建成功

  2、重定向响应

• 响应状态码3xx

  • 301：永久重定向
  • 302：暂时重定向

  3、客户端异常

• 响应状态码4xx

  • 403：请求无权限
  • 404：请求路径不存在
  • 405：请求方法不存在

  4、服务器异常

• 响应状态码5xx

  • 500：服务器异常