API接⼝开发规范
整体规范建议采⽤RESTful ⽅式来实施。
协议
API与⽤户的通信协议，总是使⽤HTTPs协议，确保交互数据的传输安全。
域名
应该尽量将API部署在专⽤域名之下。
如果确定API很简单，不会有进⼀步扩展，可以考虑放在主域名下。
api版本控制
应该将API的版本号放⼊URL。
另⼀种做法是，将版本号放在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）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下⾯这样。
HTTP请求⽅式
对于资源的具体操作类型，由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：获取某个指定商品的指定投资者信息
过滤信息
如果记录数量很多，服务器不可能都将它们返回给⽤户。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状态。
为了保障前后端的数据交互的顺畅，建议规范数据的返回，并采⽤固定的数据格式封装。
接⼝返回模板：
{
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接口规范
地址：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是⼀个GUI的WEB接⼝管理⼯具。在RAP中，您可定义接⼝的URL、请求&响应细节格式等等。通
过分析这些数据，RAP提供MOCK服务、测试服务等⾃动化⼯具。RAP同时提供⼤量企业级功能，帮助企业和团队⾼效的⼯作。
什么是RAP?
在前后端分离的开发模式下，我们通常需要定义⼀份接⼝⽂档来规范接⼝的具体信息。如⼀个请求的地址、有⼏个参数、参数名称及类型含义等等。RAP ⾸先⽅便团队录⼊、查看和管理这些接⼝⽂档，并通过分析结构化的⽂档数据，重复利⽤并⽣成⾃测数据、提供⾃测控制台等等... ⼤幅度提升开发效率。
RAP的特⾊
强⼤的GUI⼯具给⼒的⽤户体验，你将会爱上使⽤RAP来管理您的API⽂档。
完善的MOCK服务⽂档定义好的瞬间，所有接⼝已经准备就绪。有了MockJS，⽆论您的业务模型有多复杂，它都能很好的满⾜。
庞⼤的⽤户 RAP在阿⾥巴巴有200多个⼤型项⽬在使⽤，也有许多著名的公司、开源⼈⼠在使⽤。RAP跟随这些业务的成⾏⽽成长，专注细节，把握质量，经得住考验。
免费 + 专业的技术⽀持 RAP是免费的，⽽且你的技术咨询都将在24⼩时内得到答复。⼤多数情况，在1⼩时内会得到答复。
RAP是⼀个可视化接⼝管理⼯具通过分析接⼝结构，动态⽣成模拟数据，校验真实接⼝正确性，围绕接⼝定义，通过⼀系列⾃动化⼯具提升我们的协作效率。我们的⼝号：提⾼效率，回家吃晚饭！

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。