API接口设计规范

API总体设计规范

协议

API与客户端通信协议主要包含http和https，建议使用https确保交互数据的传输安全。

域名

主要包含两种形式：

1. 主域名：api.example.com
2. 子目录：example.org/api/

版本控制

版本控制主要用于App、微信小程序、软件客户端等与系统不可同时实时更新的状况，来知足须要兼容旧版本的场景。 采用多版本并存，增量发布的方式。

版本号：v{n} n表明版本号,分为整形和浮点型 整型: 大功能版本发布形式；具备当前版本状态下的全部API接口 ,例如：v1,v2 浮点型：为小版本号，只具有补充api的功能，其余api都默认调用对应大版本号的api 例如：v1.1 v2.2

1. 将版本号放入URL中： api.example.com/v{n}/ 这种方法比较方便和直观，版本号主要以整型为主。

2. 将版本号放在请求头（Request Headers）中

   headers:{
   	version: 'v{n}'
   	...
   }
   复制代码

   版本号可以使用整型、浮点型等

路径规则

路径又称"终点"（endpoint），表示API的具体网址。 在RESTful架构中，每一个网址表明一种资源（resource），因此网址中不能有动词，只能有名词，并且所用的名词每每与数据库的表格名对应。通常来讲，数据库中的表都是同种记录的"集合"（collection），因此API中的名词也应该使用复数。 举例来讲，有一个API提供动物园（zoo）的信息，还包括各类动物和雇员的信息，则它的路径应该设计成下面这样。

api.example.com/v1/products api.example.com/v1/users api.example.com/v1/employee…

请求方式

对于资源的具体操做类型，由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中类型

1. 地址栏参数

• restful 地址栏参数 /api/v1/product/122 122为产品编号，获取产品为122的信息
• get方式的查询字串，此种方式主要用于过滤查询，以下：

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

2. 请求body数据

主要用于提交新建数据等

3.请求头

用于存放请求格式信息、版本号、token密钥、语言等信息。

{
	Accept: 'application/json',     //json格式
	version: 'v1.0'                       //版本号
	Authorization: 'Bearer {access_token}',   //认证token
	language: 'zh'                      //语言
}
复制代码

返回格式

默认返回格式：

{
	code: 0,                         //状态码
	msg: 'ok',                       //提示信息
	data: {}                          //主体数据
}
复制代码

使用json格式做为响应格式，状态码分为两种：

• statusCode: 系统状态码，用于处理响应状态，与http状态码保持一致，如：200表示请求成功，500表示服务器错误。
• code：业务状态码，用于处理业务状态，通常0标识正常，可根据需求自行设计错误码对照表，参考

  

非Restful Api的需求

咱们通常以Restful Api做为接口规范，可是因为实际业务开展过程当中，可能会出现各类的api不是简单的restful 规范能实现的，所以，须要有一些api突破restful规范原则。特别是移动互联网的api设计，更须要有一些特定的api来优化数据请求的交互。

组合型：

服务端组装数据，而后返回： 把当前页面中须要用到的全部数据经过一个接口一次性返回所有数据，如：

api/v1/get-home-data 返回首页用到的全部数据

这类API有一个很是很差的地址，只要业务需求变更，这个api就须要跟着变动。

单例型：

客户端根据需求分别请求对应Api接口，在客户端完成组装。 这种模式服务端相对简单，接口复用率高。 每一个接口做用单一，如一个App首页，可能有轮播图、分类、推荐商品，则须要分别请求：

/api/v1/banners: 轮播 /api/v1/categories: 分类 /api/v1/product?is_recommend=1: 商品

开发过程当中可根据实际须要结合使用。

todo

Laravel中实践使用。

参考：github.com/mishe/blog/…