移动 APP 接口规范
一、接口概述
1.1 接口规范意义
接口是用于数据的交互,接口文档是供需双方的开发规范。移动应用接口是移动设备和业务之间进行通信的途径。实质就是以特定的规则通过接口直接操作数据库的增删改查。接口文档往往是在需求评审完成之后就需要开始编写的,并尽快文档定下来,良好的接口文档能有效减少开发人员的沟通成本。
1.2 接口分类
1.2.1 查询类接口
查询类接口是指客户端传递一些参数,服务端根据参数依据需求,前往数据库查询需要的结果返回数据的一类接口。返回类型一般有两种。第一种是返回一个对象,第二种是返回一个数组对象。
- 第一种比如登陆,客户端把用户名密码上传到接口,服务器返回用户的个人信息。
- 第二种比如获取客户,客户端把用户的身份信息上传到接口,服务器返回此身份下的所有客户数组集合。
1.2.2 操作类接口
操作类接口是指客户端通过接口进行一些增删改的操作。比如新增一个客户,修改客户信息,或者删除一个客户。服务器一般返回执行的状态(成功/失败),有的需要返回执行结果的一些信息,比如新增客户后,返回客户的ID。
1.2.3 上传下载类接口
上传下载类接口是涉及到文件传输的接口。比如上传头像,需要上传图片到服务器,服务端根据需求响应保存并返回结果。比如客户端需要显示用户头像,需要读取网络图片文件,在手机上进行显示。定义这类接口时要注意是否有必要限定上传文件的的大小。
1.2.4 推送类接口
除了客户端主动去请求服务端,获取需要信息之外。有时候,也存在服务端有消息需要通知客户端的情况,这时候就是服务端向客户端发送消息。这类需求可以通过客户端短时间内循环请求解决,也可以通过第三方专业推送解决。也可以通过自己使用socket或者xmpp等协议进行开发。
二、接口编写原则
2.1 实用性
- 数据格式:推荐使用JSON格式数据,因为JSON有较好的跨平台性,以及数据格式占用字节数较少,当然也可采用XML、TEXT作为程序开发辅助。
- 接口响应时间:APP有别于WEB服务,对服务器端要求是比较严格的,在移动端有限的带宽条件下,要求接口响应速度要快,所有在开发过程中尽量选择效率高的框架。
- 数据量:按需分配,APP客户端需要什么数据就返回什么数据,过多的数据量影响处理速度,最重要的是影响传输效率和浪费用户流量。
- API缓存:这点比较重要,不管是文件缓存还是memcache缓存。
2.2 易用性
- 接口、参数命名准确:论是接口还是参数,命名都应该有意义,让人一目了然。
- 接口拆分合理:如果不是复杂的页面,尽可能就使用一个接口;在很多的APP页面都有广告、焦点图、文章列表等,对于这些不同格式的数据,不可能都分配一个接口,这样加大了APP请求接口数,影响响应速度。建议服务器端尽可能处理好数据后通过一个接口返回给APP客户端。
- 接口数据、状态:接口必须提供明确的数据状态信息,不管是成功的,还是失败的,都必须返回给APP客户端。
- 可扩展:方便后期功能性调整,接口应具备可扩展性:文案与图片尽量由后端下发;数据列表化,灵活可配。
2.3 安全性
- 接口安全:目前一般都是在APP客户端和服务器通过约定的算法,对传递的参数值进行验证匹配。但是如果APP程序被反编译,这些约定的算法就会暴露,特别是在安卓APP中,有了算法,完全就可以通过验证模拟接口请求。
- 加密规范:在传递用户名密码时,应采用规范的加密算法如MD5、RSA、DES,进行数据通信请求。
- 接口版本控制:对于接口版本控制,需要应对不断的APP版本升级,新、旧接口的处理,因而需要关注接口版本控制。
- 时间戳:接口请求和响应都加时间戳,通过对时间戳的验证,可以一定程度上防止重放攻击。
1 | * 响应数据中包含用户隐私的字段数据,需要加 * 号 |
三、接口设计原则
- 尽量减少参数传递(尽量少的数据接收交互):在客户端发起HTTP请求接口操作时,应减少参数传递,如某些操作只需要ID不需要其他参数,这时候就应该只传递ID这个参数。
- 尽量避免接口重复性(尽量用少的链接传输多的数据):在客户端APP调用接口时,尽量提高接口复用性,减少HTTP请求,提高程序稳定性。
- 数据类型规范:客户端APP调用接口时,应标注参数数据类型,以及是否可为空或者默认字段,如标注了Int型字段,就不能返回“null”的String类型字段,否则容易造成程序APP出现数据类型解析异常。
- 设置调用html页面单独列表:调用html页面应标明是否传递安全校验参数,建议表格中采用是或者否单独字段标识。
- 编码规范:整个API接口开发过程中,应标注接口编码方式,目前建议采用UTF-8编码,UTF-8通用性以及URL请求方面都较规范。
- 请求方式:编写API接口应该标注请求方式,请求方式一般有GET和POST方式
- GET和POST方式:在数量较小情况下可以使用GET方式,但数据量超过1024字节就应该采用POST方式,避免出现请求失败或者请求异常的问题。
- 返回接口调用状态:所有API接口都应该统一标识调用的成功失败信息和规范错误编码信息,以及必要的提示字段信息。
- 安全机制:接口应规范验证签名机制,用户登录后统一调用KEY对接口安全验证。(关于KEY机制需由接口开发人员定义),对于安全系数要求较高的接口应该使用HTTPS请求,比如支付接口,订单接口,用户信息接口。
- 参数说明:应标注参数名称、是否必选、数据类型及范围、说明以及“否(必选)”传递默认的参数。
- 瘦客户端原则:客户端尽量只负责展示逻辑,不处理业务逻辑;客户端不处理金额的计算;客户端少处理请求参数的校验与约束提示。
- 考虑移动端平台特点:接口不仅仅是提供数据和功能就完事了,更应该充分考虑移动端的特性,为移动端提供更加方便、快捷的接口。
- 接口设计考虑缓存,尽量通过预加载降低对网络的依赖,首页数据可以传输更多内容,后续页可以传输索引数据。
- 对于移动客户端来说,by function (多个 API)需要多次网络交互,效率不高,也会给客户端实现增加复杂度。通常这种情况尽可能通过在服务器端 gateway 的方式来解决。最终提供 by page (统一 API)的接口。
一些移动端平台的数据约定:
- 时间日期型数据:直接返回格式化后的时间字符串或者直接返回时间戳
- 数字类型和文本类型:统一使用字符串格式
- 布尔值类型:统一使用字符串”0”和”1”来表示假和真
- 如果返回值是一个array,空数据则返回一个空array,如果返回值是一个对象,空数据则返回一个空对象
- 不返回 Null 类型数据
- 对于客户端,必须用个全局的函数来处理所有 api 的返回数据,需要有一个机制:对于某个客户端需要数据,如果api中缺失,客户端自动补上并给予默认值
四、文档编写规范
接口文档应该包含的几大类信息:目录、文档修订历史、名词解释、数据类型、系统出入参、接口描述、约定参数、常见响应码说明。接口文档要清晰、明了,包含多少个接口,每个接口的地址、参数、请求方式、数据交换格式、返回值等都要写清楚,对于字段参数应采用表格的形式规范说明。每一版的接口文档都应该有与需求文档对应的版本号。
1. 清晰的目录:目录的编写是为了APP开发人员快速定位需要的接口信息,使开发人员在最短的时间内找到需要的接口,同时也会对编写API接口人员后期的维护修改提高效率。
2. 文档修订历史:记录日期、文档版本、修改内容、修订人等信息,每一版变更的内容应该以红色文字标记,便于阅读。
日期 | 版本 | 内容 | 修改人 |
---|---|---|---|
xxxx年xx月xx日 | v1.0.1 | 部分接口改动 | xxx |
3. 名词解释:对文档中一些关键字的解释,方便在编写特定业务接口时直接使用,无需再进行说明。
4. 数据类型:基本数据类型。
|序号|类型|类型描述|参考|
|:—:|:—:|:—:|:—:|:—:|
|1|Number|数字类型|整数、长整型、单精度、双精度|
|2|String|字符串类型||
|3|Object|对象类型|任意对象类型|
|4|Boolean|布尔类型|true 或 false|
|5|Array|列表||
|6|Array<number>
|数字列表|列表中必须是同一种数字类型|
|7|Array<string>
|字符串列表||
|8|Array<object>
|对象列表|列表中必须是同一种对象类型|
|9|Array<boolean>
|布尔列表||
5. 符号定义:强制域、条件域和选用域。
序号 | 序号缩写 | 序号性质 | 符号说明 |
---|---|---|---|
1 | M | 强制域(Mandatory) | 此域为必选,否则将被认为格式出错 |
2 | C | 条件域(Conditional) | 此域在一定条件下必选 |
3 | O | 可选域(Optional) | 此域由发送方自选 |
6. 系统请求参数:操作系统、手机唯一标识码、当前客户端版本号、手机系统版本号、手机型号、数字签名、接口版本号。
名称 | 说明 | 类型 | 必填 | 最大长度 | 备注 |
---|---|---|---|---|---|
system | 操作系统 | String | M | 00-pc 01-Android 02-iOS |
|
imei | 手机 IMEI 码 | String | M/C | 15 | system 为 01 时必填 |
currentVersion | 当前客户端版本号 | String | M | 20 | |
systemVersion | 手机平台版本号 | String | M | 10 | |
model | 手机型号 | String | M | 20 | 如 N9006 |
sig | 数字签名 | String | C | ||
inteVersion | 接口版本号 | String | M | 10 | 如 1.0.1 |
7. 系统响应参数:响应码、响应消息和业务数据。
名称 | 类型 | 必填 | 最大长度 | 描述 |
---|---|---|---|---|
code | String | M | 6 | 响应码 |
msg | String | M | 128 | 响应信息 |
data | Object | M | 任意类型,由具体接口定义 |
8. 业务接口描述信息:接口名称、接口描述、请求方式、测试地址、生产地址、备注。
参数说明:参数名、含义、类型、长度、必填、备注。
参数格式:请求参数格式、响应参数格式。