api接口规范文档（api接口通俗理解）

本篇文章给大家谈谈api接口规范文档，以及api接口通俗理解对应的知识点，希望对各位有所帮助，不要忘了收藏本站喔。 今天给各位分享api接口规范文档的知识，其中也会对api接口通俗理解进行解释，如果能碰巧解决你现在面临的问题，别忘了关注本站，现在开始吧！

本文目录一览：

• 1、API_接口测试规范
• 2、API接口入门（一）：读懂API接口文档
• 3、API接口响应格式规范定义
• 4、API是什么意思？API文档又是什么意思？
• 5、什么是接口文档，如何写接口，有什么规范
• 6、什么是接口文档？

API_接口测试规范

一、接口测试

接口测试主要用于检测外部系统与系统之间以及内部各个子系统之间的交互。测试的重点是要检查数据的交换，传递和控制管理过程，以及系统间的相互逻辑依赖关系等。

二、接口测试的意义

按照分层测试模型，处于中间层的接口测试，在稳定性，效率，成本，技术，实施难度上综合来讲，是收益最大的。相较于传统的UI层次的测试，接口测试把测试提前了（时间上，架构上），并且能够覆盖到一些UI测试无法触及的功能点，提高了测试的覆盖率，对质量控制提升了信心。接口测试也更容易实现自动化持续集成，支持后端快速发版需求，利于CT（持续测试）的开展。
三、认识URL

接口主要分为2大类：

1.webservice接口

webService接口是走soap协议通过http传输，请求报文和返回报文都是xml格式的，我们在测试的时候都用通过工具（例如：soapUI）进行调用，测试。【暂时业务上用不到，不扩展】

2.http 接口

Http协议是建立在TCP协议基础之上的，当浏览器需要从服务器获取网页数据的时候，会发出一次Http请求。Http会通过TCP建立起一个到服务器的连接通道，当本次请求需要的数据完毕后，Http会立即将TCP连接断开，这个过程是很短的。所以Http连接是一种短连接，是一种无状态的连接。

3.URL解析

    在WWW上，每一信息资源都有统一的且在网上唯一的地址，该地址就叫URL（Uniform Resource Locator,统一资源定位符），它是WWW的统一资源定位标志，就是指网络地址。HTTP协议工作于客户端-服务端架构之上。浏览器作为HTTP客户端通过URL向HTTP服务端即WEB服务器发送所有请求。Web服务器根据接收到的请求后，向客户端发送响应信息。

 URL由三部分组成：资源类型、存放资源的主机域名、资源文件名。

也可认为由4部分组成：协议、主机、端口、路径

URL的一般语法格式为(带方括号[]的为可选项)：【参考 URL百度百科 】

protocol :// hostname[:port] / path / [;parameters][?query]#fragment

以下面的URL为例：

http://blog.xx.com.cn/s/blog_537ad6610102xtb1.html?tj=hist

1)、协议部分，代表页面使用的是http协议，在Internet中可以使用多种协议，如HTTP，FTP等等。在"HTTP"后面的“//”为分隔符；

2)、域名部分， blog.xx.com.cn ，也可以使用IP地址作为域名使用如：192.168.55.14:8080，其中8080为端口，域名和端口之间使用“:”作为分隔符。端口不是一个URL必须的部分，如果省略端口部分，将采用默认端口80/tcp；

3)、虚拟目录部分，从域名后的第一个“/”开始到最后一个“/”为止，是虚拟目录部分。虚拟目录也不是一个URL必须的部分。本例中的虚拟目录是“/s/”

4)、文件名部分：从域名后的最后一个“/”开始到“？”为止，是文件名部分，如果没有“?”,则是从域名后的最后一个“/”开始到“#”为止，是文件部分，如果没有“？”和“#”，那么从域名后的最后一个“/”开始到结束，都是文件名部分。本例中的文件名是“blog_537ad6610102xtb1.html”。文件名部分也不是一个URL必须的部分，如果省略该部分，则使用默认的文件名

5)、锚部分：从“#”开始到最后，都是锚部分。锚部分也不是一个URL必须的部分（可以理解为定位）

6)、参数部分：从“？”开始到“#”为止之间的部分为参数部分，又称搜索部分、查询部分。本例中的参数部分为“7.参数部分：从“？”开始到“#”为止之间的部分为参数部分，又称搜索部分、查询部分。本例中的参数部分为“boardID=5ID=24618page=1”。参数可以允许有多个参数，参数与参数之间用“”作为分隔符。”。参数可以允许有多个参数，参数与参数之间用“”作为分隔符。

四、测试范围及用例设计思路

接口测试范围分为以下5个方向：
五、测试流程

分析接口文档和需求文档（接口说明、请求方式、请求URL、请求参数、返回数据、返回实例）

接口用例设计   

编写接口测试用例

接口测试执行

输出接口测试报告。

六、如何快速评估自己的测试用例覆盖率：

1）参数验证是否完整（包括各种边界和业务规则）

2）业务需求点覆盖是否完整（单接口业务功，依赖接口业务功能）

3）接口异常场景覆盖是否完整（数据的异常）

八、接口测试用途

回归测试

非功能性测试

增量开发，持续集成的项目。

API接口入门（一）：读懂API接口文档

本文目录：

API接口是什么？

为什么我们需要API接口？

API接口的核心

一、API接口是什么？

我们来以一个常见的数学公式理解API，比如y=x+2，当x=2的时候，y=4，对么？

那此时，我们把y=x+2称为接口，x=2称为参数，y=4称为返回结果，那这个接口的功能就是能把我们输入的数加上2（注意：这里你可以发现接口自身是带有逻辑的）。

类比地，我们来理解一个常见的场景，比如现在有一个可以把经纬度转化为城市的接口，那当我输入经度是55°，纬度是88°的时候，接口通过自己的逻辑运算，返回结果告诉我：杭州市。

这样你就可以清晰地了解百度百科的官方解释了，接口就是预先定义的函数逻辑，他是供其他系统请求，然后返回结果的一个东西。

二、为什么我们需要API接口？

背景：我们的业务系统涉及多方多面，如果要一个公司或者一个系统把所有业务都做完，那未免工作量太大了吧？并且如果其他系统或公司有更好的运算逻辑，那我们在设计功能的时候可以考虑利用接口进行开发。

核心需求：利用现有接口可以降低开发成本，缩短开发成本。

举个例子：比如我是打车的APP，现在我需要在我的页面上展现地图的功能，对于我司而言，新做地图功能未免成本过高，那我们可以在高德开放平台或者百度地图的开放平台，找到地图API，这样的话我们只需要购买高德的服务，部署调用高德地图API，这样就可以快速在我们页面上线地图功能了。

三、API接口的核心

对于小白而言，初看API文档可能是一头雾水的——从哪里看，怎么看，看什么是摆在面前的问题。

其实对于产品经理而言，我们应该更关注这个公司可以提供什么样的API接口服务，比如我知道高德可以提供地图API，规划路线的API，这样的话在我们设计功能和工作中就可以想到调用他们的服务或者参考。

所以产品小白们看不懂也不用过于担心，未来工作中你也会更深入了解清楚，因为看懂并不复杂，以下是API接口的核心点，所有的说明文档离不开这5个核心点。

以下说明均以微信开放平台为例说明，文末有各开放平台的地址，大家有空可以去学习。好了，事不宜迟，现在我们来建立一个场景。

我们现在有一个APP，需要用户在购买的时候调起微信支付的API，完成购买。请各位自动进入这个场景，把自己当作一位产品经理。

1. 接口地址

现在Now，用户点击付款，我们需要告诉微信，我们要调起你们的收银台啦！但，去哪里告诉呢？这就需要接口地址了，也就相当于向微信的这条链接传输指定的数据。

一个链接地址不是我们理解的一个页面，你可以理解是一个电话号码，小白们要改变这个观念。

此时我们可以看到接口文档告诉我们链接是如下这条，那我们现在已经拨通微信的电话了。

2. 请求参数（报文）

我们现在需要告诉微信，你想调用收银台对吧。那我们需要写下来，此时生成的叫做报文，也就是你想告诉这个接口的内容是什么？相当于前文函数的输入x=2。

一般来说，报文的格式和内容都是按接口文档规定的。如下文就是微信开放平台对调起收银台的报文要求。

我们先来看前2个参数，你现在跟微信在对话，是不是应该先告诉微信，你是谁？这里微信的文档告诉你应该要用应用ID+商户号来确定你的身份，什么意思呢？

比如你是A商户，下面有a，b，c三个APP，所以微信要知道你是哪个商家，下面的哪个APP要用收银台。这是非常重要的，微信后面要把收到的钱打到对应的账户以及统计数据等。

那我们就在报文里面写下这两句话：

<appidwx2421b1c4370ec43b</appid（我的应用ID是wx2421…….）

<mch_id10000100</mch_id（我的商户号是10000…….）

好了，现在微信知道你是谁了，那你要告诉微信，你需要微信支付帮你收多少钱对吧？这里定义了货币类型和总金额，也就是收什么货币，收多少钱。

这里你看，货币类型的必填写了否，也就是说你也可以不告诉微信支付货币类型是什么，因为他在后面备注了默认是人民币。

好的，那我们写下两段报文

<free_typeCNY</ free_type （我要收人民币）

<total_fee1</total_fee（我要收1元）

好了，现在微信知道你是谁，也知道要收多少钱了，那接下来微信支付要把收钱结果告诉你呀，因为你得知道用户是成功支付了才能继续发货，服务啊等等的。所以这里我们用到通知地址，就是告诉微信，等下完事了他去哪里告诉你支付结果。那我们把地址写好：

<notify_urlhttp://wxpay.wxutil.com/pub_v2/pay/notify.v2.php</notify_url

3. 返回结果

刚刚微信支付已经去收款了，现在他要在我们留下的通知地址中，告诉我们结果了。结果无非是两种：成功收款？收款不成功？

（1）成功

很顺利，现在用户成功付钱了，并且微信也把成功的消息告诉我们了，并且他还把用户支付的一些信息也告诉我们。

那这里就是微信支付成功收款后告诉我们的信息。

应用APPID，商户号：告诉你我成功扣款的是哪家商户的哪个APPID的交易。

业务结果：成功或失败

（2）失败

在产品设计的时候，我们往往很关注失败的情况，当收款失败的时候，微信同时会告诉你失败的原因，如下图很好理解，失败的原因有很多很多种，我们在设计的时候往往要分析每种失败的原因，为每个失败的原因设计页面和用户提示，以确保用户能理解。

以上就是API接口基本运作模式的理解，下面我将继续更新API接口的一些更为深入和细节的关键元素，如请求方式/签名/加解密等等。

可供参考的开放平台网站

微信支付：https://pay.weixin.qq.com/wiki/doc/api/index.html

高德平台开放平台：https://lbs.amap.com/

API接口响应格式规范定义

由于接口规范的定义和接口的实际实现是分开的两个部分, 而且涉及到多人协作, 因此在开发过程中可能出现接口规范与实现不同步, 最终造成实际的接口不符合规范的定义, 接口规范就会慢慢失去存在的意义.

为了尽量避免这种问题, 后端在实现接口的过程中应该确保与接口规范保持一致, 一旦出现分歧, 必须同步修改接口规范, 尽可能保持沟通.

专门的api应用使用独立域名 https://api.example.com
简单的可使用api前缀区分 https://www.example.com/api

接口版本的控制，可以在程序发布时，不同版本的业务逻辑在一定程度上避免受到影响。

https://api.example.com/v {n}
应该将API的版本号放入URL。
采用多版本并存，增量发布的方式。
n代表版本号，分为整型和浮点型
整型： 大功能版本， 如v1、v2、v3 ...
浮点型： 补充功能版本， 如v1.1、v1.2、v2.1、v2.2 ...

客户端任何的修改都是需要发版的，发版需要审核流程。

客户端尽量只负责展示逻辑，不处理业务逻辑
客户端不处理金额的计算
客户端少处理请求参数的校验与约束提示

图片文案等，与校验规则类似，通过接口返回，并提供默认。

​ url连接一般采用https协议进行数据传输，可以提高数据交互过程中的安全性。

区分版本

合并接口

字段简写

无用字段清理

图片裁剪

局部刷新

预加载

其他

接口安全，防参数篡改

频率的控制

数据存储

是否需要依赖于第三方

服务降级，熔断和限流

拆分

扩展性

适配性

幂等

重复提交

部署

缓存穿透、缓存雪崩和缓存击穿

是否需要白名单

预加载

重试

异步

服务端推送或者客户端拉取数据

隔离（例如内网的中台服务，后端服务）

健康检查，后台大盘监控可视化，故障主动通知

API是什么意思？API文档又是什么意思？

API（Application Programming Interface,应用程序编程接口）是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。

API文档是一个技术内容交付文件，包含如何有效地使用和集成api的说明。它是一个简明的参考手册，包含了使用API所需的所有信息，详细介绍了函数、类、返回类型、参数等，并有教程是示例支撑。

API文档传统上是使用常规内容创建和维护工具和文本编辑器完成的。API描述格式如OpenAPI /Swagger规范具有自动文档编制流程，它使得团队更容易生成和维护API文档。

扩展资料：

Windows API

API函数包含在Windows系统目录下的动态连接库文件中。Windows API是一套用来控制Windows的各个部件的外观和行为的预先定义的Windows函数。用户的每个动作都会引发一个或几个函数的运行以告诉Windows发生了什么。

这在某种程度上很像Windows的天然代码。而其他的语言只是提供一种能自动而且更容易的访问API的方法。当你点击窗体上的一个按钮时，Windows会发送一个消息给窗体，VB获取这个调用并经过分析后生成一个特定事件。

更易理解来说：Windows系统除了协调应用程序的执行、内存的分配、系统资源的管理外，同时他也是一个很大的服务中心。

调用这个服务中心的各种服务(每一种服务就是一个函数)可以帮助应用程序达到开启视窗、描绘图形和使用周边设备等目的，由于这些函数服务的对象是应用程序，所以称之为Application Programming Interface，简称API 函数。

WIN32 API也就是MicrosoftWindows 32位平台的应用程序编程接口。凡是在 Windows工作环境底下执行的应用程序，都可以调用Windows API。

linux API

在linux中，用户编程接口API遵循了UNIX中最流行的应用编程界面标准---POSIX标准。POSIX标准是由IEEE和ISO/IEC共同开发的标准系统。

该标准基于当时现有的UNIX实践和经验，描述了操作系统的系统调用编程接口API，用于保证应用程序可以在源程序一级上在多种操作系统上移植运行。这些系统调用编程接口主要是通过C库（LIBC）来实现的。

参考资料：百度百科-api

什么是接口文档，如何写接口，有什么规范

接口文档一般是提供给商户对接时进行参考及提供帮助的一个说明文档或API。里面包含借口说明、接口列表、接口参数列表、签名/验签规则、商户应答规则等说明；
接口一般要首先考虑安全性，支付类的签名可以参考支付宝和微信支付这一类的接口文档，业务类的签名可以参考微信公众平台的接口API；
加签是根据商户号、业务参数、随机字符串或时间戳、商户密钥/公钥私钥等按照规则组装参数，然后按照一个签名规则生成签名，以保证接口的安全性；

什么是接口文档？

接口文档又称为API文档，一般是由开发人员所编写的，用来描述系统所提供接口信息的文档。 大家都根据这个接口文档进行开发，并需要一直维护和遵守。
如果想系统的学习接口测试相关的技术，可以了解一下黑马程序员的软件测试课程，里面讲的非常详细。 关于api接口规范文档和api接口通俗理解的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 api接口规范文档的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于api接口通俗理解、api接口规范文档的信息别忘了在本站进行查找喔。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。