产品必修课:接口文档怎么用?

6 评论 1.2万 浏览 144 收藏 11 分钟

编辑导读:为了方便开发和产品沟通,便有了接口文档。接口文档大多时候是给开发看的,那么产品为什么要会看接口文档呢?本文作者对此发表了自己的看法,一起来看看吧。

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

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

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

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

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

一、什么是接口文档?

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

但x怎么输,会出现什么样的y,就需要通过接口文档来了解。就比如下图的表格,当你按照“输入参数”输入“委托方式”、“分支机构”等参数时,这个接口就会告诉你“资产账户”是什么。

恒生统一接入平台_周边接口规范(期货,期权_20210812).xls

二、产品为什么要能看懂接口文档?

接口一般来讲分为两种:

  • 程序内部的接口:方法与方法、模块与模块之间的交互,如登录发帖,发帖就必须要登录,如果不登录不能发帖,发帖和登录这两个模块之间就要有交互,就会抛出一个接口,进行内部系统调用。
  • 系统对外的接口:从别人的网站或服务器上获取资源或信息,对方不会提供数据库,只能提供一个写好的方法来获取数据,如购物网站和第三方支付,购物网站支付时可选择第三方支付方法,但第三方不会提供自己的数据库给购物网站,只会提供一个接口,供购物网站进行调用。

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

首先,在迭代或依赖其他系统时,你能明确知道有哪些资源。例如下面这个关于微信菜单创建的接口,从这个接口的参数“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.qq.com/wxaapi/newtmpl/addtemplate?access_token=ACCESS_TOKEN

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

  • 协议部分:指访问服务器获取资源时,需要使用哪种协议。常用的有http、https、ftp协议等。本例中的为https。
  • 域名部分:指资源宿主服务器的主机名或IP地址。本例中的域名部分为:api.weixin.qq.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.qq.com/doc/offiaccount/Subscription_Messages/api.html

金融交易统一接入平台

https://ufx.hs.net/

高德地图API

http://lbs.amap.com/api/jsapi-v2/summary

 

作者:阿宅的产品笔记;公众号:阿宅的产品笔记(PMZZnote)

本文由 @公众号阿宅的产品笔记 原创发布于人人都是产品经理。未经许可,禁止转载

题图来自Unsplash,基于CC0协议

给作者打赏,鼓励TA抓紧创作!
更多精彩内容,请关注人人都是产品经理微信公众号或下载App
评论
评论请登录
  1. 为啥接口文档需要产品经理来写???

    来自广东 回复
    1. 哈哈哈我也一脸懵逼,正常的话 是哪个岗位来写呀?

      来自浙江 回复
    2. 后端写,前端用;产品写明白页面上需要哪些参数怎么展示传递就行了,参数在接口里怎么命名,什么格式,数据用不用拼接前后端商量下就出来了

      来自北京 回复
    3. 仔细读题《接口文档怎么 用 》

      回复
  2. 内容量很丰富,学到了。接口文档的确是经常出现的情况

    来自陕西 回复
  3. 学到了,很详细,清晰明确,把复杂的内容系统化,达到高效传达的目的

    来自中国 回复