整体规范建议采用 RESTful 方式来实施。
协议
API 与客户端通讯协议主要包含 http 和 https，建议使用 https 确保交互数据的传输安全。
域名
应该尽量将 API 部署在专用域名之下。
Go
https://api.example.com
如果确定 API 很简单，不会有进一步扩展，可以考虑放在主域名下。
Go
https://example.org/api/
api 版本控制
应该将 API 的版本号放入 URL。
CSS
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）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
Go
https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees
HTTP 请求方式
对于资源的具体操作类型，由 HTTP 动词表示。
常用的 HTTP 动词有下面四个（括号里是对应的 SQL 命令）。
-
GET（SELECT）：从服务器取出资源（一项或多项）。
-
POST（CREATE）：在服务器新建一个资源。
-
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
-
DELETE（DELETE）：从服务器删除资源。
下面是一些例子。
1）GET /product：列出所有商品
2）POST /product：新建一个商品
3）GET /product/ID：获取某个指定商品的信息
4）PUT /product/ID：更新某个指定商品的信息
5）DELETE /product/ID：删除某个商品
6）GET /product/ID/purchase ：列出某个指定商品的所有投资者
7）get /product/ID/purchase/ID：获取某个指定商品的指定投资者信息
过滤信息
如果记录数量很多，服务器不可能都将它们返回给用户。API 应该提供参数，过滤返回结果。
下面是一些常见的参数。
1）?limit=10：指定返回记录的数量
2）?offset=10：指定返回记录的开始位置。
3）?page=2&per_page=100：指定第几页，以及每页的记录数。
4）?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
5）?producy_type=1：指定筛选条件
API 传入参数
传入参数分为 4 种类型：
地址栏参数
-
restful 地址栏参数 /api/v1/product/122。122 为产品编号，获取产品为 122 的信息
-
get 方式的查询字串 见过滤信息小节
请求 body 数据
-
cookie
-
request header
-
cookie 和 header 一般都是用于 OAuth 认证的 2 种途径
返回数据
只要 api 接口成功接到请求，就不能返回 200 以外的 HTTP 状态。
为了保障前后端的数据交互的顺畅，建议规范数据的返回，并采用固定的数据格式封装。
接口返回模板：
Less
{
status:0,
data:{}||[],
msg:’’
}
status 接口的执行的状态
=0 表示成功
<0 表示有异常
Data 接口的主数据
可以根据实际返回数组或 JSON 对象
Msg 信息
当 status!=0 都应该有错误信息
非 Restful Api 的需求
由于实际业务开展过程中，可能会出现各种的 api 不是简单的 restful 规范能实现的，因此，需要有一些 api 突破 restful 规范原则。特别是移动互联网的 api 设计，更需要有一些特定的 api 来优化数据请求的交互。
页面级的 api
把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据
举例
api/v1/get-home-data 返回首页用到的所有数据
这类 API 有一个非常不好的地址，只要业务需求变动，这个 api 就需要跟着变更。
自定义组合 api
把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端，服务端根据请求内容，一次性把所有数据合并返回, 相比于页面级 api，具备更高的灵活性，同时又能很容易的实现页面级的 api 功能。
规范
地址：api/v1/batApi
传入参数：
[](javascript:void(0); "复制代码")
Bash
data:[
{url:'api1',type:'get',data:{...}},
{url:'api2',type:'get',data:{...}},
{url:'api3',type:'get',data:{...}},
{url:'api4',type:'get',data:{...}}
]
``` [](javascript:void(0); "复制代码")[](//common.cnblogs.com/images/copycode.gif)
**返回数据**
[](javascript:void(0); "复制代码")[](//common.cnblogs.com/images/copycode.gif) Lua
{ status:0, msg:'',
data:[
{status:0,msg:'',data:[]},
{status:-1,msg:'',data:{}},
{status:1,msg:'',data:{}},
{status:0,msg:'',data:[]},
]
}
Api 共建平台
========
RAP 是一个 GUI 的 WEB 接口管理工具。在 RAP 中，您可定义接口的 URL、请求 & 响应细节格式等等。通过分析这些数据，RAP 提供 MOCK 服务、测试服务等自动化工具。RAP 同时提供大量企业级功能，帮助企业和团队高效的工作。
什么是 RAP?
--------
在前后端分离的开发模式下，我们通常需要定义一份接口文档来规范接口的具体信息。如一个请求的地址、有几个参数、参数名称及类型含义等等。RAP 首先方便团队录入、查看和管理这些接口文档，并通过分析结构化的文档数据，重复利用并生成自测数据、提供自测控制台等等... 大幅度提升开发效率。
RAP 的特色
-------
强大的 GUI 工具 给力的用户体验，你将会爱上使用 RAP 来管理您的 API 文档。
完善的 MOCK 服务 文档定义好的瞬间，所有接口已经准备就绪。有了 MockJS，无论您的业务模型有多复杂，它都能很好的满足。
庞大的用户群 RAP 在阿里巴巴有 200 多个大型项目在使用，也有许多著名的公司、开源人士在使用。RAP 跟随这些业务的成行而成长，专注细节，把握质量，经得住考验。
免费 + 专业的技术支持 RAP 是免费的，而且你的技术咨询都将在 24 小时内得到答复。大多数情况，在 1 小时内会得到答复。
RAP 是一个可视化接口管理工具 通过分析接口结构，动态生成模拟数据，校验真实接口正确性， 围绕接口定义，通过一系列自动化工具提升我们的协作效率。我们的口号：提高效率，回家吃晚饭！
* [协议](#tid-3W8Ac4)
* [域名](#tid-mstXaX)
* [api 版本控制](#tid-PRQcrQ)
* [API 路径规则](#tid-3Tnsda)
* [HTTP 请求方式](#tid-cFMeMA)
* [过滤信息](#tid-MfNEhc)
* [API 传入参数](#tid-3jdXDW)
* [返回数据](#tid-hzB62R)
* [非 Restful Api 的需求](#tid-NMsJ6t)
* [页面级的 api](#tid-WJtG7F)
* [自定义组合 api](#tid-Q4a7Jk)
* [Api 共建平台](#tid-t38Apj)
* [什么是 RAP?](#tid-KWJP6W)
* [RAP 的特色](#tid-AZiyGR)