在设计接口时，有很多因素要考虑，如接口的业务定位，接口的安全性，接口的可扩展性、接口的稳定性、接口的跨域性、接口的协议规则、接口的路径规则、接口单一原则、接口过滤和接口组合等诸多因素，本篇文章将简要分析这些因素。

接口API设计规范

整体规范建议采用RESTful 方式来实施

协议

API与用户的通信协议，总是使用HTTPS协议，确保交互数据的传输安全。

域名

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

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

API版本控制

应该将API的版本号放入URL。https://api.example.com/v{n}/
另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。

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

API 路径规则

路径又称”终点”（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请求方式

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：获取某个指定商品的指定投资者信息

过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

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

API 传入参数

参入参数分为4种类型：

地址栏参数
* restful 地址栏参数 /api/v1/product/122 122为产品编号，获取产品为122的信息
* get方式的查询字串 见过滤信息小节
请求body数据
cookie
request header

cookie和header 一般都是用于OAuth认证的2种途径

返回数据

只要API接口成功接到请求，就不能返回200以外的HTTP状态。
为了保障前后端的数据交互的顺畅，建议规范数据的返回，并采用固定的数据格式封装。

接口返回模板：

{
	"version":0,
    "status":"0正常 小于0异常   大于0部分失败",
    "errMsg":"status非正常时展示",
    "ts":"时间戳"
	"data":{"一定要返回JSON对象，如果返回数组类型，下次需要增加一个字段的时候就没法兼容旧接口了"}
}

非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: 商品

优点：
1.更好的能适应需求变更。例如首页要显示信息 a,b,c，结果下个需求，c 不要在首页中显示，移到其他页面了。这样的话，接口都不需要动。假如接口按照页面给的话，要改两个接口。服务端，客户度都要动，还要重新联调。
2.接口按页面给出，对一些数据量比较大的页面，很可能出现一个接口，数据很大的情况。可能性能上，会比较麻烦。
3.很多分页加载的列表，也只能按接口给出列表需要的数据，不可能一次性把页面上的数据都全部一次性给出。
4.有利于客户端做部分数据缓存的工作。
缺点：
1.就是为了加载一个页面，可能要加载很多接口，导致页面加载速度有点慢。这个我们都是靠优化来解决，有些数据的获取，可以放在登录、APP 初始化的时候，数据量比较小的页面，分担一些通用数据获取的工作。有些不常更改的数据，可以直接通过版本控制的方式，缓存在客户端。
2.部分数据接口之间，有依赖关系。这个也要处理好。

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

页面级的api

把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据

举例

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

这类API有一个非常不好的地址，只要业务需求变动，这个api就需要跟着变更。

自定义组合api

把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端，服务端根据请求内容，一次性把所有数据合并返回,相比于页面级api，具备更高的灵活性，同时又能很容易的实现页面级的api功能。

规范

地址：api/v1/batApi

传入参数：

data:[
{url:’api1’,type:’get’,data:{…}},
{url:’api2’,type:’get’,data:{…}},
{url:’api3’,type:’get’,data:{…}},
{url:’api4’,type:’get’,data:{…}}
]

返回数据

{status:0,msg:’’,
data:[
{status:0,msg:’’,data:[]},
{status:-1,msg:’’,data:{}},
{status:1,msg:’’,data:{}},
{status:0,msg:’’,data:[]},
]
}

API共建平台

RAP这个学习一下子