手机客户端接口文档
版本历史
版本/状态 | 作者 | 参与者 | 起止日期 | 备注 |
V1.0/草稿 | xx | 移动小组 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
接口说明5
参数说明6
正常返回结果6
错误返回列表6
上传下载类6
上传文件6
接口说明6
参数说明7
正常返回结果7
错误返回列表7
下载文件7
接口说明7
参数说明7
正常返回结果8
错误返回列表8
推送类接口8
推送消息8
接口说明8
参数说明8
正常返回结果8
错误返回列表8
通用返回格式9
正确返回9
接口说明9
参数说明9
正常返回结果9
错误返回列表9
错误返回9
接口说明9
参数说明10
正常返回结果10
错误返回列表10
附录10
通用错误返回列表10
URL地址信息11
主机地址11
安全机制11
验证签名机制11
其他11
列表数据为空的返回11
概述
有关接口
接口是纯数据的交互
APP接口是移动设备和业务之间进行通信的途径。实质就是以特定的规则通过接口直接操作数据库的增删改查。
接口的分类
查询类接口
查询类接口是指客户端传递一些参数,服务端根据参数依据需求,前往数据库查询需要的结果返回数据的一类接口。
返回类型一般有两种。第一种是返回一个对象,第二种是返回一个数组对象。
第一种比如登陆,客户端把用户名密码上传到接口,服务器返回用户的个人信息。
第二种比如获取客户,客户端把用户的身份信息上传到接口,服务器返回此身份下的所有客户数组集合。
操作类接口
操作类接口是指,客户端通过接口进行一些增删改的操作。比如新增一个客户,修改客户信息,或者删除一个客户。服务器一般返回执行的状态,有的需要返回执行结果的一些信息,比如新增客户后,返回客户的ID。
上传下载类接口
上传下载类接口是涉及到文件传输的接口。比如上传头像,需要上传片到服务器,服务端根据需求响应保存并返回结果。比如客户端需要显示用户头像,需要读取网络片文件,在手机上进行显示。
推送类接口
除了客户端主动去请求服务端,获取需要信息之外。有时候,也存在服务端有消息需要通知客户端的情况,这时候就是服务端向客户端发送消息。这类需求可以通过客户端短时间类循环请求解决,也可以通过第三方专业推送解决。也可以通过自己使用socket或者xmpp等协议进行开发。
查询类接口格式规范
获取单条对象信息
请求格式
URL |
|
支持格式 | JOSN |
HTTP请求方式 | POST |
是否登录验证 |
|
请求数限制 |
|
参数说明
参数名 | 必选 | 类型及范围 | 说明 |
xxx | true | String | 用户名 |
|
|
|
|
|
|
|
|
正常返回结果
返回键 | 类型 | 返回值 | 说明 |
result | String | 结果代码信号 | ok 结果成功, fail结果失败 |
Response | Object | 响应体 |
|
Key1 | int | 响应字段值 |
|
Key2 | String | 响应字段值 |
|
Key3 | Object | 响应字段值 | 可以依然包含对象体 |
Key3_Key1 | int | 响应字段值 |
|
|
|
|
|
|
|
|
|
{ 'result':'ok' , 'Response': { 'userName': 'Mary', 'sex': 1, 'Address': [ { 'city': 'JiNan' }, { 'county': 'LiXia' } ] } } |
错误返回列表
详见:通用错误返回列表
获取列表对象信息
请求格式
URL |
|
支持格式 | JOSN |
HTTP请求方式 | POST |
是否登录验证 |
|
请求数限制 |
|
参数说明
参数名 | 必选 | 类型及范围 | 说明 |
xxx | true | String | 用户名 |
Page | false | int | 第几页,不传递默认第一页 |
Size | false | int | 一页多少条,不传递默认20条 |
|
|
|
|
|
|
|
|
正常返回结果
返回键 | 类型 | 返回值 | 说明 |
result | String | 结果代码信号 |
|
Response | Object | 响应体 |
|
LastUpdateTime | String | 最后一条更新时间 | 根据此时间判断新旧 |
ThisPageNumber | int | 当前页条数 | 判断是否为空,是否有下页 |
DataList | Array[Object] | 对象列表 | 时间倒序排列 |
|
|
|
|
|
|
|
|
|
|
|
|
{ “result”:”ok” , 'Response': { 'LastUpdateTime': '2012-12-11 22:01:09', 'ThisPageNumber': 2, 'DataList': [ { 'id': 1, 'date': '2014-07-24', 'detail': '15064002716', 'points': 50 }, { 'id': 2, 'date': '2014-07-24', 'detail': '15064002716', 'points': 50 } ] } } |
错误返回列表
详见:通用错误返回列表
操作类接口
新增操作
接口说明
URL |
|
支持格式 | JOSN |
HTTP请求方式 | POST |
是否登录验证 |
|
请求数限制 |
|
参数说明
参数名 | 必选 | 类型及范围 | 说明 |
xxx | true | String | 用户名 |
xxx | true | String |
|
xxx | true | String |
|
xxx | true | String |
|
|
|
|
|
正常返回结果
返回键 | 类型 | 返回值 | 说明 |
result | String | 结果代码信号 |
|
Response | Object | 响应体 |
|
id | int | 增数据的ID或者标志 |
|
text | String | 操作提示语 | 如添加客户成功,可为空 |
{ “result”:”ok” , 'Response': { 'id': 1, 'text': '' } } |
错误返回列表
详见:通用错误返回列表
修改操作
接口说明
URL |
|
支持格式 | JOSN |
HTTP请求方式 | POST |
是否登录验证 |
|
请求数限制 |
|
参数说明
参数名 | 必选 | 类型及范围 | 说明 |
xxx | true | String | 用户名 |
xxx | true | String |
|
xxx | true | String |
|
xxx | true | String |
|
|
|
|
|
正常返回结果
返回键 | 类型 | 返回值 | 说明 |
result | String | 结果代码信号 |
|
Response | Object | 响应体 |
|
id | int | 数据的ID或者标志 |
|
text | String | 操作提示语 | 如修改客户成功,可为空 |
{ “result”:”ok” , 'Response': { 'id': 1, 'text': '' } } |
错误返回列表
详见:通用错误返回列表
删除操作
接口说明
URL |
|
支持格式 | JOSN |
HTTP请求方式 | POST |
是否登录验证 |
|
请求数限制 |
|
参数说明
参数名 | 必选 | 类型及范围 | 说明 |
xxx | true | String | 用户名 |
xxx | true | String |
|
|
|
|
|
|
|
|
|
|
|
|
|
正常返回结果
返回键 | 类型 | 返回值 | 说明 |
result | String | 结果代码信号 |
|
Response | Object | 响应体 |
|
id | int | 数据的ID或者标志 |
|
text | String | 操作提示语 | 如删除客户成功,可为空 |
{ “result”:”ok” , 'Response': { 'id': 1, 'text': '亲,删除客户成功' } } |
错误返回列表
详见:通用错误返回列表
上传下载类
上传文件
接口说明
URL |
|
支持格式 | JOSN |
HTTP请求方式 | POST |
是否登录验证 |
|
请求数限制 |
|
参数说明
参数名 | 必选 | 类型及范围 | 说明 |
xxx | true | String | 用户名 |
xxx | true | File | 值为文件类型,处理同Web中的表单FILE一样 |
|
|
|
|
|
|
|
|
|
|
|
|
正常返回结果
返回键 | 类型 | 返回值 | 说明 |
result | String | 结果代码信号 |
|
Response | Object | 响应体 |
|
filePath | String | 文件存放的绝对路径 | 上传 |
|
|
|
|
{ “result”:”ok” , 'Response': { 'filePath': 'http://www.baidu.com/logo.gif' } } |
错误返回列表
详见:通用错误返回列表
下载文件
接口说明
URL |
|
支持格式 | JOSN |
HTTP请求方式 | POST |
是否登录验证 |
|
请求数限制 |
|
参数说明
参数名 | 必选 | 类型及范围 | 说明 |
xxx | true | String | 文件网络绝对路径 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
正常返回结果
返回键 | 类型 | 返回值 | 说明 |
|
|
| 确保文件可以正常访问下载 |
|
|
|
|
|
|
|
|
|
|
|
|
|
错误返回列表
详见:通用错误返回列表
推送类接口
推送消息
接口说明
URL |
|
支持格式 | JOSN |
HTTP请求方式 | POST |
是否登录验证 |
|
请求数限制 |
|
参数说明
参数名 | 必选 | 类型及范围 | 说明 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
正常返回结果
返回键 | 类型 | 返回值 | 说明 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
错误返回列表
详见:通用错误返回列表
通用返回格式
正确返回
接口说明
URL |
|
支持格式 | JOSN |
HTTP请求方式 | POST |
是否登录验证 |
|
请求数限制 |
|
参数说明
参数名 | 必选 | 类型及范围 | 说明 |
xxx | true | String | 用户名 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
正常返回结果
返回键 | 类型 | 返回值 | 说明 |
result | String | 结果代码信号 |
|
Response | Object | 响应体 |
|
|
|
|
|
|
|
|
|
{ “result”:”ok” , 'Response': {
} } |
错误返回列表
详见:通用错误返回列表
错误返回
接口说明
URL |
|
支持格式 | JOSN |
HTTP请求方式 | POST |
是否登录验证 |
|
请求数限制 |
|
参数说明
参数名 | 必选 | 类型及范围 | 说明 |
xxx | true | String | 用户名 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
正常返回结果
返回键 | 类型 | 返回值 | 说明 |
result | String | 结果代码信号 |
|
Response | Object | 响应体 |
|
errorText | String | 错误信息 |
|
|
|
|
|
{ 'result':'fail' , 'Response': { 'errorCode': -998 , 'errorText': '用户名密码错误' } } |
错误返回列表
详见:通用错误返回列表
附录
通用错误返回列表
errorCode | 表示 | 说明 |
-999 | 通用错误 | 只用于一处,或者无关紧要的提示性,错误 |
-998 | 用户名密码错误 |
|
-997 | 用户登陆超时或别处登录 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
URL地址信息
主机地址
URL列表
URL | 描述 | 备注 |
API/login | 用户登录 | 无需验证 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
安全机制
验证签名机制
生成Token
其他
列表数据为空的返回
文章为作者独立观点,不代表 股票程序化软件自动交易接口观点