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

时间: 2019-12-01阅读: 130标签: api

原则上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设计时经常需要和开发、业务讨论的关键点和注意点~~

原文 http://www.woshipm.com/pd/2772820.html

吐血推荐

1.站长广告联盟: 整理了目前主流的广告联盟平台,如果你有流量,可以作为参考选择适合你的平台点击进入...

2.休闲娱乐: 直播/交友    优惠券领取   网页游戏   H5游戏

链接: http://www.fly63.com/article/detial/7119

HTML5常用API

该API可以用来检测页面对于用户的可见性,即返回用户当前浏览的页面或标签tap的状态变化。 在最小化浏览器、切换tap页面时生效.(如需对app中几个webview进行切换操作时

vue之按钮权限及优雅请求API

系统开发中按钮级权限控制也是非常重要的功能之一,可以严格控制不同角色用户所拥有的功能权限。首先可以通过vue的自定义指令来控制按钮(div,link也阔以)等的显示与否以及是否禁用状态。

webService和Restful

restful是一种架构风格,其核心是面向资源,更简单;而webService底层SOAP协议,主要核心是面向活动;两个都是通过web请求调用接口

使用 JS 来动态操作 css ,你知道几种方法?

JavaScript 可以说是交互之王,它作为脚本语言加上许多 Web Api 进一步扩展了它的特性集,更加丰富界面交互的可操作性。这类 API 的例子包括WebGL API、Canvas API、DOM API,还有一组不太为人所知的 CSS API

在 Node.js 上运行 Flutter Web 应用和 API

大量的跨平台应用开发框架,使你可以编写一次代码,然后在 Android,iOS 等多个平台上甚至在台式机上运行。你可能听说过一些流行的框架,例如 Ionic,Xamarin 和 React Native。另一个相对较新的框架是 Flutter

vue-next 函数式 api

在分享 vue-next 各个子模块的实现之前,我觉的有必要比较全面的整理下 vue-next 中提出的函数式 api,了解这些的话,无论是对于源码的阅读,还是当正式版发布时开始学习,应该都会有起到一定的辅助作用

解锁设计优质API的五种秘籍

如今,随着我们构建软件方式的变化,以及API平台的爆炸式激增,各大公司都必须以更快的速度构建出自己的产品、并推向市场。目前,几乎所有的软件需求都需要通过API来提供相应的解决方案,其中包括:支付类API、通信类API

Moment.js常用API速查

日常开发经常会用Moment.js来处理时间,现对频繁使用的几个API做下整理,以便日后查阅。

SDK 与API之间的关系和联系

SDK(Software Development Kit,软件开发工具包)一般都是一些软件工程师为特定的软件包、软件框架、硬件平台、操作系统等建立应用软件时的开发工具的集合,比如提供安卓开发工具、或者基于硬件开发的服务等。也有针对某项软件功能的SDK

基于 React 和 Redux 的 API 集成解决方案

在前端开发的过程中,我们可能会花不少的时间去集成 API、与 API 联调、或者解决 API 变动带来的问题。如果你也希望减轻这部分负担,提高团队的开发效率,那么这篇文章一定会对你有所帮助。文章中使用到的技术栈主要有:

fly63.com版权所有,内容以共享、参考、研究为目的,不存在任何商业目的。其版权属原作者所有,如有侵权,请与小编联系!情况属实本人将予以删除!

文章投稿关于web前端网站点搜索站长推荐网站地图站长QQ:522607023

小程序专栏: 土味情话心理测试脑筋急转弯幽默笑话段子句子语录成语大全