作者： BNDong
cnblogs.com/bn dong/p/6139598.html
总体规格建议采用rest风格的方式实施。 协议API与客户端的通信协议主要包括http和https，建议使用https来确保交互式数据的传输安全。
域名应尽可能位于专用域名下。
如果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的特定网址。
在rest风格的体系结构中，每个网站都表示资源(resource )，因此网站上没有动词，只有名词。 此外，所使用的名词通常与数据库中的表名相对应。 一般来说，数据库中的表是同类记录的“集合”(collection )，因此API中的名词也应该使用多个。
例如，如果一个API提供动物园(zoo )的信息，同时还包含各种动物和员工的信息，则路径应设计如下：
3359 API.example.com/v1/products 3359 API.example.com/v1/employees http请求方式资源中
常用的HTTP动词有以下四个(括号中是相应的SQL命令) :
GET（SELECT）:从服务器中检索资源。
POST（CREATE）:在服务器上创建新资源。
PUT（UPDATE）:在服务器上更新资源(客户端提供更改后的完整资源)。
DELETE（DELETE）:从服务器中删除资源。
让我举几个例子。
1 )获取/产品：列出所有商品
2 ) POST /product :制作新商品
3 ) GET /product/ID :获取某指定商品的信息
4 ) PUT /product/ID :更新某指定商品的信息
5 ) DELETE /product/ID :删除某商品
6 )获取/产品/id /采购)列出特定商品的所有投资者
7 ) get /product/ID/purchase/ID :获取某指定商品的指定投资者信息
如果过滤信息记录数较多，则服务无法将它们返回给用户。 API必须提供参数并筛选结果。
下面是一些常见的参数。
1 )？ limit=10 :指定要返回的记录数
2 )？ offset=10 :指定返回记录的开始位置。
3 )？ page=2per_page=100 :指定第几页和每页的记录数。
4 )？ sortby=nameorder=asc :指定按哪个属性对返回的结果进行排序以及排序顺序。
5 )？ producy_type=1:指定过滤条件
有四种类型的API输入参数输入参数：
地址栏参数
rest风格的地址栏参数/api/v1/product/122。 122是产品编号，取得产品为122的信息
get方式的查询字符串请参照过滤器信息一节
请求主体数据
饼干
请求头
cookie和header一般是用于OAuth认证的两种方法
只要返回数据的api接口成功接收到请求，就无法返回200以外的HTTP状态。
为了方便前后数据的交换，建议规范数据的发送和接收，并将其封装为固定的数据格式。
界面返回模板：
{status:0，data:{}||[]，msg :’} http://www.Sina.com /
=0表示成功
p><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
传入参数：
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是一个可视化接口管理工具 通过分析接口结构，动态生成模拟数据，校验真实接口正确性， 围绕接口定义，通过一系列自动化工具提升我们的协作效率。我们的口号：提高效率，回家吃晚饭！
推荐好文 强大，10k+点赞的 SpringBoot 后台管理系统竟然出了详细教程！分享一套基于SpringBoot和Vue的企业级中后台开源项目，代码很规范！能挣钱的，开源 SpringBoot 商城系统，功能超全，超漂亮！