API接口设计的4个要点 api接口设计怎么做( 二 ) _生活百科

二、核心业务字段&接口约束产品经理虽然不需要定义API所有的字段信息，但是跟业务需求有关的字段产品经理需要明确清晰。
1. 入参（1）鉴权字段信息
调用第三方平台接口通常需要进行接口鉴权，服务端判断用户端是否有调用接口的权限；这里跟产品经理相关的是作为产品需要设计应用管理，包括：应用列表、应用创建、应用详情、应用配置、应用删除等操作；以百度AI平台，应用列表如下：

文章插图
其中AppID、API Key和Secret Key为创建应用时自动生成，接口鉴权所需要的access_token必须通过API key和Secret key请求服务端获取。
（2）核心业务字段
产品经理需要根据业务需求明确接口入参中需要哪些字段信息以及字段支持的类型，以百度AI平台的菜品识别为例：

文章插图
业务需求：识别图片中是哪种菜品；
产品需求：

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

注意点：设计接口核心业务字段，要尽量提高接口的通用性，以此适配更多的用户场景，比如top_num和阈值的开放，即泛化接口能力，将更多的主动权交由接口用户配置。
（3）字段信息约束条件
字段约束条件是为了保证接口的安全性，这点是产品经理跟业务方沟通达成一致后提供给开发小伙伴的；仍然以上面的菜品识别为例：

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

注：设置参数的一点小技巧，为了保证算法效果，有时算法会默认设置参数，即用户设置的阈值低于默认参数，则不接受输入，采用默认，用户是无感知的；
2. 出参调用接口就会有返回信息，产品需要根据业务需求定义返回的核心字段信息，这次以百度AI开放平台手势识别为例，其中跟业务需求相关的关键字段包括：

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

文章插图

三、接口限流接口限流也是为了保障系统的安全性，因为有时业务方因为业务扩展导致调用量激增，容易引起服务端宕机；限流就类似于电闸的保险丝保证请求量超过接口上限时系统可以拒绝请求或排队，以此保证系统的安全性；
产品经理需要实现对业务充分评估，给出合理评估量，如TPS（每秒处理的请求量）；这样既不会造成系统资源的浪费，也保证业务正常运行；
注：与上面接口响应机制对应，同步接口一般需要给出峰值tps和响应时间，异步接口需要给出日调量即可；
四、接口测试接口测试虽然是测试小姐姐的工作，测试内容也覆盖众多，但是作为产品可以简单了解以下内容即可，如，
（1）接口可用性，即接口是否可以正常调用，正常返回结果，异常正确处理，正常返回错误码等；