来源|Kevin改变世界的点滴
做产品经理会调研各式各样的第三方需求能力。
以满足产品提供用户所需要的功能，比如第三方登录、图像识别、风控算法，都有专注的服务厂商。
通过接入第三方能力，企业无需自己花时间和精力投入在具有较高技术壁垒或时间成本的需求上。就算企业自己做，也做不好。
所以，产品经理学会看API接口文档，是一项产品经理的基本功，可以提升产品设计质量、以及和开发沟通效率。
那么，一个合格的接口文档包含什么内容？
▲ 接口文档范围
有了接口文档，我们可以知道第三方能力的功能逻辑、功能的边界、和接入的条件。比如要接口当天的天气接口信息，可以查看下面的接口。
比如万年历的接口文档描述了接口的传输数据是当天详情。
▲ 万年历的能力描述
接口文档的编写规范
各个公司甚至一家公司的不同项目组，接口文档都可能不一样。项目成员的前后端开发工程师会去定义接口，并且随着需求变化，接口文档也需要不断维护。
所以经常有不懂接口文档的产品经理如果让开发同学你把后台功能给其他部门直接用、或者某某客户端你把你的app直接给某某部门后台用。
这个时候，“开发的拳头就捏紧了。”
在一家公司不同项目下，接口仍然有规范不一致的情况，更何况公司之间的数据交流。这也是为什么有产品经理的公司，都不会选择外包。外包开发意味着后期维护在接口、规范上都是不清楚的，难以搞清楚对方的撰写代码思路和潜在问题。
接口规范集中在4点维度上去做规范
新增post
修改put
删除（delete）
获取（get）
通过上面4个定义接口的权限。
2.URI定义
以/a开头，如果你的账户涉及到需要登录权限、比如我们的微信开放平台、第三方单点登录，则需要/u。如果是通过后台要查询数据库列表，则以/search结尾。如果是查询前台的列表则以/list结婚
3.请求参数和返回参数
两个类型参数都分为5列：字段、说明、类型、备注、是否必填。
▲ 接口的参数案例
字段：类的属性
说明：中文解释字段什么意思
类：属性类型
有string（字符串）、number（整数）、object（对象）、arrar（数组）四种类型。
备注：接口的能力或逻辑解释，或者可以写一下列子，有的情况有列子会让开发人员看得懂一些。比如json
返回参数：返回参数和产品经理的异常是非常相关的。比如
-
只会返回接口调用成功或失败
-
返回某些参数
-
返回列表
上面3种返回形式都包含内容有区别。
第一种
新增、删除、修改等，只需要一个结果即可。
第二种
结构体有2个，第一个是code/mesaeg/dat ，第二个是data里写返回的参数，data是object类型
第三种
过于偏向开发知识，就不再叙述。
接口文档主要有什么
▲ 喜马拉雅接口文档
请求后会有响应。在代码层面会有如下的显示规则
serid Long 用户ID
usernick String 用户登录名
sessionkey String 用户会话key
示例
请求
“XXXX”
响应
{“usersession11”:
{“userid”:”12512313”,
“usernck”:” name1 “,
”sessionkey”:”2122323232332435353”,
}}
响应有结果，并且显示调用成功则表示接口调通。
开放平台文档字段说明
第一：请求
说明请求地址，告诉如何调用接口
第二：调用秘钥
比如喜马拉雅要求申请秘钥，走开放平台账户协议进行注册。
第三：API测试
接通后会显示什么结果，如何知道接口是否接通？就需要在接口文档里面知道成功的参数
▲ 请求测试
同理可以在微信开放平台上可以看到
▲ 微信开放平台的接口文档描述
多个接口文档组成的接口目录让产品经理和开发者快速查询功能点，以集成到自己的产品中。所以产品经理做第三方能力调研，最多时间的就是去看对方的接口文档。
包括对接口的描述，比如下图是地理位置获取。可以看到在该接口下，可以看到地理位置获取失败、成果的提示。
▲ 微信公众平台提供位置信息的接口