怎么看懂接口文档
本文转载自CSDN博主「陪学」的原创文章
原文链接：https://blog.csdn.net/weixin_42058609/article/details/105147681
-------------------
日常产品开发过程中，涉及前后端数据交互的时候，往往会离不开接口调用，尽管产品经理一般不需要写接口文档（负责接口中间层产品经理除外），但对接口了解，对于需求沟通、需求传达还是很有帮助的。
接口是什么？
API（ApplicationProgramming Interface）即应用程序接口。
可以认为 API 是一个软件组件或是一个Web 服务与外界进行的交互的接口。从另一个角度说，API是一套协议，规定了我们与外界的沟通方式：如何发送请求和接收响应。
API的本质是根据调用者的输入内容来返回一些其他内容。
举个栗子，这和我们生活中接触的USB接口的原理是类似的，我们知道接入某个接口就能实现某种功能，例如：U盘插入电脑USB接口就可以相互传输文件。
产品经理看懂接口文档的意义
1）了解技术开放能力，产品设计更合理
例如，我们公司是做微信公众号生态相关的产品的，微信开放了许多公众号的接口，如果不了解微信的接口文档，往往就不知道如何应用到自己的产品。
2）通过接口构建产品功能。
通过现有接口来搭建产品，通过对接口、技术的理解，能够更深入地衡量产品的数据边界，对针对性的进行产品特色功能设计。
接口组成
接口分为四部分:
1、方法:
新增(post) 修改(put) 删除(delete) 获取(get)
2、格式：
以/a开头，如果需要登录才能调用的接口后面需要加/u(如新增、修改；前台的用户个人信息，资金信息等)，即：/a/u；中间一般放表名或者能表达这个接口的单词；
get方法，如果是后台通过搜索查询列表，那么以/search结尾，如果是前台的查询列表，以/list结尾。
3、请求参数和返回参数，
都分为5列：字段、说明、类型、备注、是否必填
字段：类的属性
说明：中文释义；
类型：属性类型；
备注：一些解释，或者可以写一下例子，比如负责json结构的情况，最好写上例子（这里不是产品写），好让前端能更好理解；
是否必填：字段的是否必填。
4、返回参数结构的几种情况
如果只返回接口调用成功还是失败（如新增、删除、修改等），则只有一个结构体：code和message两个参数；
如果要返回某些参数，则有两个结构体：1是code/mesage/data，2是data里写返回的参数,data是object类型；
如果要返回列表，那么有三个结构体，1是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5个参数，其中list是Arrary类型，list里放object，object里是具体的参数。
接口请求方式
基于http协议的常用请求方式是post和get；两者的主要区别如下：
（1）get请求方式是将请求参数放到url中，post是将参数放到requstbody中，
直接影响是get的请求参数存在长度限制，post无限制；其次是get将参数放到url中安全性弱于post；
（2）get请求方式用户端和服务端只产生一次交互，post请求方式用户端会和服务端产生两次交互，
例：快递小哥是用户端，你是服务端，get就像常来你们小区和你认识的快递员直接将快件送到你家，你跟他说声谢谢；post就像新来的快递员先打个电话问下你在家吗？你告诉他你在家呢，过了5分钟他将快递送到你家了，你跟他说声谢谢；
接口响应机制
接口的响应机制包括：
同步接口
异步接口
同步接口即实时返回消息给调用方，异步接口就是可以延迟返回消息给调用方；实时性要求高的且只能线性工作的需要采用同步接口，其他可以优先使用异步接口；
不同的场景，同样的服务接口会被要求同步或异步，以人脸识别中的人脸注册为例：
（1）刷脸支付：
以支付宝为例，使用之前需要按照步骤采集人脸，后台调用人脸注册将当前人脸注册进人脸库并和该支付宝账号信息绑定，这一步人脸注册通常是同步接口，因为不会要求用户在APP前等待太久，需要及时返回注册成功信息；
（2）客流系统：
商超使用的客流系统一般已经采用人脸识别取代头肩模型，这样不仅可以统计人数还可以统计人次，其中对于首次识别的陌生人脸通常需要注册进陌生人脸库，这里的人脸注册一般为异步接口，因为大型商超每天数十万客流且对于陌生人无会员信息，所以不需要实时注册，只要进入队列能在当日24小时内注册完即可；
关于API的接口在设计时，开发一般会要求产品确定接口的响应机制；其他的开发都会自己完成；
很多产品经理刚接触API接口工作时，脑子一片空白，不理解接口（API）是什么，更看不懂接口开发文档。那么，作为一个不懂技术的产品经理，该如何看懂接口文档。
API文档结构
API接口文档一般分为接口描述、接口地址、请求方法、请求参数、相应内容、错误代码、实例几个部分。
1、接口描述
简单描述接口的逻辑和作用
2、接口地址
接口的正式url和接口测试的url，需求方通过调用接口url，获取响应内容
3、请求方法
一般来说，接口最常见的请求方法为GET和POST两种方式，即读接口和写接口。通过这两种方式，实现对数据的增删查改。增删改本质都是写的动作。
4、请求参数
即需要请求的字段名的名称和规则：都是哪些字段，字段的类型是什么，是否必填字段等等
5、响应内容
接口返回的字段名称和规则。
注意：大部分开发往往不会把所有的字段罗列，只会列出比较重要的字段。当你发现，接口文档中没有你需求的字段，别着急找开发，可以看下实例中，有没有需求的字段。
6、错误代码
对接口的错误用代码进行归类，以便能快速找到错误原因，解决问题。
7、实例
实际调用时的响应的内容。
核心业务字段&接口约束
产品经理虽然不需要定义API文档里所有的字段信息，但是跟业务需求有关的字段产品经理需要明确清晰。
下面就来看看API文档中的核心业务字段与接口约束。
1. 入参
（1）鉴权字段信息
调用第三方平台接口通常需要进行接口鉴权，服务端判断用户端是否有调用接口的权限；产品经理设计应用管理时，要了解：应用列表、应用创建、应用详情、应用配置、应用删除等操作；
以百度AI平台为例，应用列表如下：
AppID、API Key和Secret Key为创建应用时自动生成，接口鉴权所需要的access_token必须通过API key和Secret key请求服务端获取。
（2）核心业务字段
产品经理要根据业务需求明确接口入参中需要哪些字段信息以及字段支持的类型，
以百度AI平台的菜品识别为例：
业务需求：
识别图片中的菜品；
产品详细需求：
用户输入图片，图片支持采用base64和URL格式；top_num
top_num，提高接口的通用性，方便用户后续场景扩展，因此支持配置返回菜品数量且排序；
阈值，开放识别阈值，方便用户根据实际识别效果调整，提高准确率；
注意点：设计接口核心业务字段，要尽量提高接口的通用性，以此适配更多的用户场景，比如top_num和阈值的开放，即泛化接口能力，将更多的主动权交由接口用户配置。
（3）字段信息约束条件
字段约束条件是为了保证接口的安全性，这点是产品经理跟业务方沟通达成一致后提供给开发小伙伴的；
以菜品识别为例：
图片要求：采用base64图片编码、大小不超过4M，最短边大于15PX，最长边小于4096px，图片格式：jpg/png/bmp
图片需要限制文件大小和分辨率大小，文件大小只需要上限，分辨率大小需要包括上限和下限，下限是为了保证算法效果，比如在目标检测中小目标容易检测失败；
top_num需要限制下限，不得小于0，不设上限，可以接受算法返回的所有结果；
阈值根据格式确定，可以是0-100，可以是0-1；
注：为了保证算法效果，有时算法会默认设置参数，即用户设置的阈值低于默认参数，则不接受输入，采用默认，用户是无感知的；
2. 出参
调用接口会有返回信息。产品经理需要根据业务需求定义返回的核心字段信息。
以百度AI开放平台手势识别为例，跟业务需求相关的关键字段包括：
result_num、result，即一张图片中识别的手势结果数量，和具体的手势信息；
result为json数组，包括手势的类别、手势检测框的位置信息【一般识别类算法底层是检测+识别两步】、和手势类别的置信度；
其中result中的一些字段信息，产品可以根据业务需求进行增减，比如目标检测框的位置信息，一般业务不需要就可以省略。
