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

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

　　笔者查阅了百度、腾讯、旷视、阿里的云平台发觉在视觉方面均都采用的是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平台的食材辨识为例：

　　业务需求：识别图片中是哪种食材；

　　产品需求：

　　输入图片，图片支持一般采用base64和URL格式；top_num，提高插口的通用性，方便用户后续场景扩充，因此支持配置返回食材数目且排序；阈值，开放辨识阀值，方便用户按照实际辨识疗效调整，提高准确率；

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

　　（3）字段信息约束条件

　　字段约束条件是为了保证插口的安全性，这点是产品总监跟业务方沟通达成一致后提供给开发小伙伴的；仍然以里面的食材辨识为例：

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

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

　　2. 出参

　　调用插口都会有返回信息，产品须要依照业务需求定义返回的核心数组信息，这次以百度AI开放平台手势辨识为例，其中跟业务需求相关的关键数组包括：

　　三、接口限流

　　接口限流也是为了保障系统的安全性，因为有时业务方由于业务扩充造成调用量猛增，容易造成服务端宕机；限流就类似于空开的保险丝保证恳求量超过插口上限时系统可以拒绝恳求或排队，以此保证系统的安全性；

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

　　注：与前面插口响应机制对应，同步插口通常须要给出峰值tps和响应时间，异步插口须要给出日调量即可；

　　四、接口测试

　　接口测试似乎是测试小妹哥的工作，测试内容也覆盖诸多，但是作为产品可以简单了解以下内容即可，如，

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

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

　　（3）边界规则依循，即插口是否满足业务规则和数组约束条件；

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

　　结语