产品必修课：接口文档怎么用？

文章目录 [+]

又到了周末，快乐开黑开始！
阿宅兴冲冲得找小伙伴上号，结果小伙伴尔康摆手：“等一下，我先开电脑喷下开拓。
”

阿宅一局酣战之后，又来找到小伙伴：“好了没？”“没好，我被开拓喷了，是我的需求bug，老板还骂我了，你看。
”

产品必修课：接口文档怎么用？产品必修课：接口文档怎么用？人工智能

为了让小伙伴尽快上号，我们开始一起复盘：“这是关于基金购买流程的需求，我在这个地方须要先明确基金的委托类型，我问爷爷找爸爸终于把这个理清楚了，可以分为购买、赎回、定投。
结果上线后才创造分类没定义完全。
”“这玩意不是接口里写得明明白白吗？”

（图片来自网络侵删）

“！
！
！
！
接口文档是个啥！
我怎么从来没看过！
”

“你啊你，都做了半年理财产品了，竟然连这个都不知道。
那本宅就大发慈悲教教你吧，记住来日诰日给我一根冰糖葫芦。
”

什么是接口文档？

首先，什么是接口？你可以把它大略理解为一个函数，你输入x，它就会见告你y。
你无需知道这个函数的逻辑，只须要知道输入什么样的问题，会得到什么样的答案就可以了。

但x怎么输，会涌现什么样的y，就须要通过接口文档来理解。
就比如下图的表格，当你按照“输入参数”输入“委托办法”、“分支机构”等参数时，这个接口就会见告你“资产账户”是什么。

产品为什么要能看懂接口文档？

接口一样平常来讲分为两种：

(1)程序内部的接口：方法与方法、模块与模块之间的交互，如登录发帖，发帖就必须要登录，如果不登录不能发帖，发帖和登录这两个模块之间就要有交互，就会抛出一个接口，进行内部系统调用。

(2)系统对外的接口：从别人的网站或做事器上获取资源或信息，对方不会供应数据库，只能供应一个写好的方法来获取数据，如购物网站和第三方支付，购物网站支付时可选择第三方支付方法，但第三方不会供应自己的数据库给购物网站，只会供应一个接口，供购物网站进行调用。

这便意味着开拓的人乃至团队都不一样，为了便于沟通，便有了接口文档。
从这里可以看出，接口文档大多时候是给开拓看的，那么产品为什么要会看这玩意呢？

首先，在迭代或依赖其他系统时，你能明确知道有哪些资源。
例如下面这个关于微信菜单创建的接口，从这个接口的参数“type”的解释，我们就能清楚的知道，微信菜单能实现3种交互：一是直接点击打开网页；二是推送；三是跳转小程序。

其次，业务很繁芜的时候可以通过接口反推，例如我们在做期货需求时，不清楚期货产品分为哪些，这时我们便可以找到恒生的接口查查它的数据字典，结果就创造答案竟如此清晰：

再次，在写需求文档或和开拓沟通创造说不明白时，也可以通过文档来澄清。
例如做内容排序时可能有多个韶光：创建韶光、更新韶光、操作韶光等等。
而你想调用的韶光和开拓理解的可能会存在差异，这时你便可拉出接口文档见告他我要的便是CreateTime。

当然啦，接口文档还有很多妙用，比如作为撕逼利器、装逼神器等等，欢迎大家在留言区写下你的文档故事~

接口文档怎么看？

接口文档有这么多好处，那我们怎么去读懂它呢？在这里我们用微信订阅关照的接口文档作为学习材料。

如上图所示，接口常日分为四部分：要求方法、url、要求参数、返回参数：

1）要求方法：常用的方法便是下面的四种——GET、PUT、POST、DELETE。

GET要求会向数据库发索取数据的要求，从而来获取信息。
该要求就像数据库的select操作一样，只是用来查询一下数据，不会修正、增加数据，不会影响资源的内容，即该要求不会产生副浸染。
与GET不同的是，PUT要求是向做事器端发送数据的，从而改变信息。
该要求就像数据库的update操作一样，用来修正数据的内容，但是不会增加数据的种类等。
POST要求同PUT要求类似，都是向做事器端发送数据的，但是该要求会改变数据的种类等资源，就像数据库的insert操作一样，会创建新的内容。
目前所有的提交操作险些都是用POST要求。
DELETE要求顾名思义，便是用来删除某一个资源的，该要求就像数据库的delete操作。

这个观点产品经理大略理解即可，一样平常不考

2）url：以微信微信订阅关照接口的url为例https://api.weixin.***.com/wxaapi/newtmpl/addtemplate?access_token=ACCESS_TOKEN

我们可以把这个 URL 分解成 5部分：

协议部分：指访问做事器获取资源时，须要利用哪种协议。
常用的有http、https、ftp协议等。
本例中的为https。
域名部分：指资源宿主理事器的主机名或IP地址。
本例中的域名部分为：api.weixin.***.com。
URL中也可以利用IP作为域名。
端口部分：域名和端口之间利用“:“作为分隔符，端口不是一个URL必须的部分。
http做事的默认端口是80，这种情形下端口号可以省略，如果利用了其他端口必须有名，例如：http://www.azhai.com:90/。
虚拟目录部分：该部分解释了资源位于做事器的什么地方。
从域名后的第一个“/“开始到末了一个“/“为止，是虚拟目录部分。
本例中的虚拟目录是“/wxaapi/newtmpl/”。
文件名部分：从域名的末了一个”/“开始到”?“为止，是文件名部分。
如果没有”?“，则是从域名后的末了一个“/”开始到“#”为止；如果没有“？”和“#”，那么从域名后的末了一个“/”开始到结束，都是文件名部分。
文件名部分也不是一个URL必须的部分，如果省略该部分，则利用默认的文件名。
本例中的文件名是“addtemplate”。

同样，产品经理不须要非常明白。

3）要求参数和返回参数：要求参数和返回参数都分为：字段、解释、类型、默认值、是否必填这5列。

字段：类的属性

解释：中文释义

类型：属性的类型，只有String、Number、Object、Array四大类

备注：一些阐明语，或者写大略的示例

4）返回参数，要分两种情形谈论：

只返回接口调用成功或者失落败：code、reason

返回参数：字段、解释、类型、默认值、是否必填

一些可供学习的网址

微信开放文档

https://developers.weixin.***.com/doc/offiaccount/Subscription_Messages/api.html