开发经验集合

移动应用接口定义及文档编写规范

2017-07-04  本文已影响0人  山那边的大叔

接口定义备忘录

接口规范的意义

接口是用于数据的交互,接口文档是供需双方的开发规范。移动应用接口是移动设备和业务之间进行通信的途径。实质就是以特定的规则通过接口直接操作数据库的增删改查。接口文档往往是在需求评审完成之后就需要开始编写的,并尽快文档定下来,良好的接口文档能有效减少开发人员的沟通成本。

接口分类

(一)查询类接口

查询类接口是指客户端传递一些参数,服务端根据参数依据需求,前往数据库查询需要的结果返回数据的一类接口。返回类型一般有两种。第一种是返回一个对象,第二种是返回一个数组对象。
a.第一种比如登陆,客户端把用户名密码上传到接口,服务器返回用户的个人信息。
b.第二种比如获取客户,客户端把用户的身份信息上传到接口,服务器返回此身份下的所有客户数组集合。

(二)操作类接口

操作类接口是指客户端通过接口进行一些增删改的操作。比如新增一个客户,修改客户信息,或者删除一个客户。服务器一般返回执行的状态(成功/失败),有的需要返回执行结果的一些信息,比如新增客户后,返回客户的ID。

(三)上传下载类接口

上传下载类接口是涉及到文件传输的接口。比如上传头像,需要上传图片到服务器,服务端根据需求响应保存并返回结果。比如客户端需要显示用户头像,需要读取网络图片文件,在手机上进行显示。定义这类接口时要注意是否有必要限定上传文件的的大小。

(四)推送类接口

除了客户端主动去请求服务端,获取需要信息之外。有时候,也存在服务端有消息需要通知客户端的情况,这时候就是服务端向客户端发送消息。这类需求可以通过客户端短时间内循环请求解决,也可以通过第三方专业推送解决。也可以通过自己使用socket或者xmpp等协议进行开发。

接口编写原则

(一)实用性

1.数据格式:推荐使用JSON格式数据,因为JSON有较好的跨平台性,以及数据格式占用字节数较少,当然也可采用XML、TEXT作为程序开发辅助。

2.接口响应时间:APP有别于WEB服务,对服务器端要求是比较严格的,在移动端有限的带宽条件下,要求接口响应速度要快,所有在开发过程中尽量选择效率高的框架。

3.数据量:按需分配,APP客户端需要什么数据就返回什么数据,过多的数据量影响处理速度,最重要的是影响传输效率和浪费用户流量。

4.API缓存:这点比较重要,不管是文件缓存还是memcache缓存。

(二)易用性

1.接口、参数命名准确:论是接口还是参数,命名都应该有意义,让人一目了然。

2.接口拆分合理:如果不是复杂的页面,尽可能就使用一个接口;在很多的APP页面都有广告、焦点图、文章列表等,对于这些不同格式的数据,不可能都分配一个接口,这样加大了APP请求接口数,影响响应速度。建议服务器端尽可能处理好数据后通过一个接口返回给APP客户端。

3.接口数据、状态:接口必须提供明确的数据状态信息,不管是成功的,还是失败的,都必须返回给APP客户端。

4.可扩展:方便后期功能性调整,接口应具备可扩展性。

(三)安全性

1.接口安全:目前一般都是在APP客户端和服务器通过约定的算法,对传递的参数值进行验证匹配。但是如果APP程序被反编译,这些约定的算法就会暴露,特别是在安卓APP中,有了算法,完全就可以通过验证模拟接口请求。

2.加密规范:在传递用户名密码时,应采用规范的加密算法如MD5、RSA、DES,进行数据通信请求。

3.接口版本控制:对于接口版本控制,需要应对不断的APP版本升级,新、旧接口的处理,因而需要关注接口版本控制。

4.时间戳:接口请求和响应都加时间戳,通过对时间戳的验证,可以一定程度上防止重放攻击。

接口设计原则

1.尽量减少参数传递:在客户端发起HTTP请求接口操作时,应减少参数传递,如某些操作只需要ID不需要其他参数,这时候就应该只传递ID这个参数。

2.尽量避免接口重复性:在客户端APP调用接口时,尽量提高接口复用性,减少HTTP请求,提高程序稳定性。

3.数据类型规范:客户端APP调用接口时,应标注参数数据类型,以及是否可为空或者默认字段,如标注了Int型字段,就不能返回“null”的String类型字段,否则容易造成程序APP出现数据类型解析异常。

4.设置调用html页面单独列表:调用html页面应标明是否传递安全校验参数,建议表格中采用是或者否单独字段标识。

5.编码规范:整个API接口开发过程中,应标注接口编码方式,目前建议采用UTF-8编码,UTF-8通用性以及URL请求方面都较规范。

6.请求方式:编写API接口应该标注请求方式,请求方式一般有GET和POST方式

7.GET和POST方式:在数量较小情况下可以使用GET方式,但数据量超过1024字节就应该采用POST方式,避免出现请求失败或者请求异常的问题。

8.返回接口调用状态:所有API接口都应该统一标识调用的成功失败信息和规范错误编码信息,以及必要的提示字段信息。

9.安全机制:接口应规范验证签名机制,用户登录后统一调用KEY对接口安全验证。(关于KEY机制需由接口开发人员定义),对于安全系数要求较高的接口应该使用HTTPS请求,比如支付接口,订单接口,用户信息接口。

10.参数说明:应标注参数名称、是否必选、数据类型及范围、说明以及“否(必选)”传递默认的参数。

文档编写规范

接口文档应该包含的几大类信息:目录、文档修订历史、名词解释、数据类型、系统出入参、接口描述、约定参数、常见响应码说明。接口文档要清晰、明了,包含多少个接口,每个接口的地址、参数、请求方式、数据交换格式、返回值等都要写清楚,对于字段参数应采用表格的形式规范说明。每一版的接口文档都应该有与需求文档对应的版本号。

1.清晰的目录:目录的编写是为了APP开发人员快速定位需要的接口信息,使开发人员在最短的时间内找到需要的接口,同时也会对编写API接口人员后期的维护修改提高效率。

2.文档修订历史:记录日期、文档版本、修改内容、修订人等信息,每一版变更的内容应该以红色文字标记,便于阅读,如下图。

3.名词解释:对文档中一些关键字的解释,方便在编写特定业务接口时直接使用,无需再进行说明。

4.数据类型:基本数据类型,如下图。

5.符号定义:强制域、条件域和选用域,如下图。

6.系统请求参数:操作系统、手机唯一标识码、当前客户端版本号、手机系统版本号、手机型号、数字签名、接口版本号,如下图表。

7.系统响应参数:响应码、响应消息和业务数据,如下图表。

8.业务接口描述信息:接口名称、接口描述、请求方式、测试地址、生产地址、备注。
      参数说明:参数名、含义、类型、长度、必填、备注。
      参数格式:请求参数格式、响应参数格式。

8.常见响应码:约定的常见系统错误码,如下图。

上一篇下一篇

猜你喜欢

热点阅读