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

更新日期: 2019-12-01阅读: 2.4k标签: 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

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

浏览器中的图像识别 API

在 Native 开发中,Android 和 IOS 平台都在系统层面直接提供给了应用开发识别图像的一些能力,比如对于二维码/条形码的识别,Android 可以使用 barcode API 、 iOS 可以使用 CIQRCodeFeature API 。

JavaScript的API设计原则

Js的API设计原则总共包含了七个大块。系卤煮自己总结的一些经验和教训。本篇博文同时也参考了其他一些文章,相关地址会在后面贴出来。很难做到详尽充实,如果有好的建议或者不对的地方,还望不吝赐教斧正。

适合写api接口文档的管理工具有哪些?

现在越来越流行前后端分离开发,使用ajax交互。所以api接口文档就变的十分有意义了,目前市场有哪些比较优秀的接口文档管理工具呢?比如:MinDoc,eoLinker,apizza,RAML,Swagger等等

前后端分离,如何防止api接口被恶意调用或攻击

无论网站,还是App目前基本都是基于api接口模式的开发,那么api的安全就尤为重要了。目前攻击最常见的就是“短信轰炸机”,由于短信接口验证是App,网站检验用户手机号最真实的途径,使用短信验证码在提供便利的同时,也成了呗恶意攻击的对象,那么如何才能防止被恶意调用呢?

JSON API免费接口_ 免费的天气预报、地图、IP、手机信息查询、翻译、新闻等api接口

整理提供最新的各种免费JSON接口,其中有部分需要用JSONP调用。方面前端同学的学习或在网站中的使用,包括:免费的天气预报、地图、IP、手机信息查询、翻译、新闻等api接口

什么是RESTful API?

要弄清楚什么是RESTful API,首先要弄清楚什么是REST。REST -- REpresentational State Transfer,英语的直译就是“表现层状态转移”。如果看这个概念,估计没几个人能明白是什么意思。

认识 Fetch API

Fetch API 已经作为现代浏览器中异步网络请求的标准方法,其使用 Promise 作为基本构造要素。Fetch 在主流浏览器中都有很好的支持,除了IE。

用一个通俗的例子讲清楚API

随着移动互联网的发展, 基于互联网的应用正变得越来越普及,在这个过程中,更多的平台将自身的资源开放给开发者来调用。对外提供的API 调用使得平台之间的内容关联性更强,同时这些开放的平台也为用户、开发者和中小网站带来了更大的价值。

docker提供api访问

环境centos,添加deamon.json后,dockerd命令可以启动docker,这时请求 127.0.0.1:2375 可以正常访问,使用systemctl无法启动docker的情况.无法启动docker:查看当前的docker配置

构建API的最佳编程语言是什么?

你是否正在设计第一个Web应用程序?也许你过去已经建立了一些,但是目前也正在寻找语言的变化以提高你的技能,或尝试新的东西。有了所有信息,就很难决定为下一个产品或项目选择哪种编程语言。

点击更多...

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