API接口设计，需要注意这4点

原则上API接口设计一般出现在开发的详细设计中，但是随着诸多公司建立开放平台，产品经理也逐渐需要能理解API接口，尤其是做平台性的产品，还要学会定义接口。本文就关于产品经理在设计接口中需要定义什么、需要注意什么来展开陈述。

看到人人都是产品经理社区已经有关于API接口的相关介绍，因此本文就不做过多的关于API接口概念方面的介绍。

一、了解API的常识

在做接口设计时，如果是新手，建议多参考并了解不同开放平台的接口样式，比如百度、旷视、腾讯等，从中可以发现一些共识；

1. 常用的通信协议

调用第三方平台接口需要进行系统间的通信，目前常用的协议是http和https；简单理解https是http的加密版，可以将用户到服务端请求的信息进行加密，避免因明文传输被截获而获知用户信息。

基于http协议的接口具有轻量级、跨平台、和跨语言的特点，为了适应不同的开发者，目前各个第三方平台都会提供基于各种常用语言的接口形式，因此大多采用http或https协议；举例，百度、科大讯飞：

• 科大讯飞的物体识别请求URL：http://tupapi.xfyun.cn/v1/currency
• 百度的菜品识别请求URL： https://aip.baidubce.com/rest/2.0/image-classify/v2/dish

笔者查阅了百度、腾讯、旷视、阿里的云平台发现在视觉方面均都采用的是https协议；对于视觉，图片数据本身包含的信息就很丰富，尤其是人脸，因此采用https还是有利于保护用户隐私信息的。

2. 接口的请求方式

了解接口的请求方式有助于了解用户端和服务端间的交互方式，基于http协议的常用请求方式是post和get；两者的主要区别如下：

（1）直观区别：get请求方式是将请求参数放到url中，post是将参数放到requst body中，所带来的的直接影响是get的请求参数存在长度限制，post无限制；其次是get将参数放到url中安全性弱于post；

（2）深度区别：get请求方式用户端和服务端只产生一次交互，post请求方式用户端会和服务端产生两次交互，举例：快递小哥是用户端，你是服务端，则get就像常来你们小区和你认识的快递员直接将快件送到你家，你跟他说声谢谢；post就像新来的快递员先打个电话问下你在家吗？你告诉他你在家呢，过了5分钟他将快递送到你家了，你跟他说声谢谢；

目前百度、腾讯、旷视的图像识别接口均采用的是post请求方式

3. 接口响应机制

最后了解接口的响应机制：同步接口和异步接口；简单理解同步接口即实时返回消息给调用方，异步接口就是可以延迟返回消息给调用方；实时性要求高的且只能线性工作的需要采用同步接口，其他可以优先使用异步接口；当然不同的场景，同样的服务接口会被要求同步或异步；以人脸识别中的人脸注册为例：

（1）刷脸支付：以支付宝为例，使用之前需要按照步骤采集人脸，后台会调用人脸注册将当前人脸注册进人脸库并和该支付宝账号信息绑定，这一步人脸注册通常是同步接口，因为不会要求用户在APP前等待太久，需要及时返回注册成功信息；

（2）客流系统：现在商超使用的客流系统一般已经采用人脸识别取代头肩模型，这样不仅可以统计人数还可以统计人次，其中对于首次识别的陌生人脸通常需要注册进陌生人脸库，这里的人脸注册一般为异步接口，因为大型商超每天数十万客流且对于陌生人无会员信息，所以不需要实时注册，只要进入队列能在当日24小时内注册完即可；

小结

以上关于API的接口常识在设计接口的时候，开发一般都会要求产品确定接口的响应机制；其他的开发都会自己完成；但作为开放平台的产品经常会对接开发，多了解些常识既可以跟自己的开发有更多的共同语言沟通，也可以在对接用户的时候可以跟用户的开发简单解释。

二、核心业务字段&接口约束

产品经理虽然不需要定义API所有的字段信息，但是跟业务需求有关的字段产品经理需要明确清晰。

1. 入参

（1）鉴权字段信息

调用第三方平台接口通常需要进行接口鉴权，服务端判断用户端是否有调用接口的权限；这里跟产品经理相关的是作为产品需要设计应用管理，包括：应用列表、应用创建、应用详情、应用配置、应用删除等操作；以百度AI平台，应用列表如下：

其中AppID、API Key和Secret Key为创建应用时自动生成，接口鉴权所需要的access_token必须通过API key和Secret key请求服务端获取。

（2）核心业务字段

产品经理需要根据业务需求明确接口入参中需要哪些字段信息以及字段支持的类型，以百度AI平台的菜品识别为例：
业务需求：识别图片中是哪种菜品；

产品需求：

1. 输入图片，图片支持通常采用base64和URL格式；
2. top_num，提高接口的通用性，方便用户后续场景扩展，因此支持配置返回菜品数量且排序；
3. 阈值，开放识别阈值，方便用户根据实际识别效果调整，提高准确率；

注意点：设计接口核心业务字段，要尽量提高接口的通用性，以此适配更多的用户场景，比如top_num和阈值的开放，即泛化接口能力，将更多的主动权交由接口用户配置。

（3）字段信息约束条件

字段约束条件是为了保证接口的安全性，这点是产品经理跟业务方沟通达成一致后提供给开发小伙伴的；仍然以上面的菜品识别为例：

1. 图片需要限制文件大小和分辨率大小，文件大小只需要上限，分辨率大小需要包括上限和下限，下限是为了保证算法效果，比如在目标检测中小目标容易检测失败；
2. top_num需要限制下限，不得小于0，不设上限，可以接受算法返回的所有结果；
3. 阈值根据格式确定，可以是0-100，可以是0-1；

注： 设置参数的一点小技巧，为了保证算法效果，有时算法会默认设置参数，即用户设置的阈值低于默认参数，则不接受输入，采用默认，用户是无感知的；

2. 出参

调用接口就会有返回信息，产品需要根据业务需求定义返回的核心字段信息，这次以百度AI开放平台手势识别为例，其中跟业务需求相关的关键字段包括：

• result_num、result，即一张图片中识别的手势结果数量，和具体的手势信息；
• result为json数组，包括手势的类别、手势检测框的位置信息【一般识别类算法底层是检测+识别两步】、和手势类别的置信度；
• 其中result中的一些字段信息，产品可以根据业务需求进行增减，比如目标检测框的位置信息，一般业务不需要就可以省略；

三、接口限流

接口限流也是为了保障系统的安全性，因为有时业务方因为业务扩展导致调用量激增，容易引起服务端宕机；限流就类似于电闸的保险丝保证请求量超过接口上限时系统可以拒绝请求或排队，以此保证系统的安全性；

产品经理需要实现对业务充分评估，给出合理评估量，如TPS（每秒处理的请求量）；这样既不会造成系统资源的浪费，也保证业务正常运行；

注： 与上面接口响应机制对应，同步接口一般需要给出峰值tps和响应时间，异步接口需要给出日调量即可；

四、接口测试

接口测试虽然是测试小姐姐的工作，测试内容也覆盖众多，但是作为产品可以简单了解以下内容即可，如，

（1）接口可用性，即接口是否可以正常调用，正常返回结果，异常正确处理，正常返回错误码等；

（2）业务需求覆盖，即接口输入输出是否遵循产品需求文档描述；

（3）边界规则遵循，即接口是否满足业务规则和字段约束条件；

（4）性能条件，通常接口上线前需要经过压测达到性能指标才可，包括某并发量下的tps和耗时等；

结语

以上即是本人作为产品经理对于API设计时经常需要和开发、业务讨论的关键点和注意点~~

#相关阅读#

《三步法完成AI产品需求分析》

《 如何做一款SDK产品？》

 

本文由 @Eric_d 原创发布于人人都是产品经理。未经许可，禁止转载

题图来自Unsplash，基于CC0协议