APP接口规范文档
手机客户端接口文档
如果对您有帮助 ，请多多支持.多少都是您的心意与支持，一分也是爱，再次感谢！！！
支付宝赞赏：
记得点击下面的余额宝，红包可能要大些。注意：余额宝红包有效期三天（72小时） 在有效期内
余额宝红包使用完或过期才能有机会领取下个余额宝红包，感谢大家的支持！您的支持，我会继续分享更多的文章，欢迎关注！
|
文件状态： [ ] 草稿 [√] 正式发布 [ ] 正在修改 |
文件标识： |
|
|
当前版本： |
1.0 |
|
|
作 者： |
xxx |
|
|
完成日期： |
|
版 本 历 史
|
版本/状态 |
作者 |
参与者 |
起止日期 |
备注 |
|
V1.0/草稿 |
xx |
移动小组 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
目录
一、概述
1.1 有关接口
1.1.1接口是纯数据的交互
APP接口是移动设备和业务之间进行通信的途径。实质就是以特定的规则通过接口直接操作数据库的增删改查。
1.2 接口的分类
1.2.1查询类接口
查询类接口是指客户端传递一些参数，服务端根据参数依据需求，前往数据库查询需要的结果返回数据的一类接口。
返回类型一般有两种。第一种是返回一个对象，第二种是返回一个数组对象。
第一种比如登陆，客户端把用户名密码上传到接口，服务器返回用户的个人信息。
第二种比如获取客户，客户端把用户的身份信息上传到接口，服务器返回此身份下的所有客户数组集合。
1.2.2 操作类接口
操作类接口是指，客户端通过接口进行一些增删改的操作。比如新增一个客户，修改客户信息，或者删除一个客户。服务器一般返回执行的状态，有的需要返回执行结果的一些信息，比如新增客户后，返回客户的ID。
1.2.3上传下载类接口
上传下载类接口是涉及到文件传输的接口。比如上传头像，需要上传图片到服务器，服务端根据需求响应保存并返回结果。比如客户端需要显示用户头像，需要读取网络图片文件，在手机上进行显示。
1.2.4推送类接口
除了客户端主动去请求服务端，获取需要信息之外。有时候，也存在服务端有消息需要通知客户端的情况，这时候就是服务端向客户端发送消息。这类需求可以通过客户端短时间类循环请求解决，也可以通过第三方专业推送解决。也可以通过自己使用socket或者xmpp等协议进行开发。
二、查询类接口格式规范
2.1获取单条对象信息
2.1.1 请求格式
|
URL |
|
|
支持格式 |
JOSN |
|
HTTP请求方式 |
POST |
|
是否登录验证 |
|
|
请求数限制 |
|
2.1.2参数说明
|
参数名 |
必选 |
类型及范围 |
说明 |
|
xxx |
true |
String |
用户名 |
|
|
|
|
|
|
|
|
|
|
2.1.3正常返回结果
|
返回键 |
类型 |
返回值 |
说明 |
|
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" } ] } } |
|||
2.1.4错误返回列表
详见：通用错误返回列表
2.2获取列表对象信息
2.2.1 请求格式
|
URL |
|
|
支持格式 |
JOSN |
|
HTTP请求方式 |
POST |
|
是否登录验证 |
|
|
请求数限制 |
|
2.2.2参数说明
|
参数名 |
必选 |
类型及范围 |
说明 |
|
xxx |
true |
String |
用户名 |
|
Page |
false |
int |
第几页，不传递默认第一页 |
|
Size |
false |
int |
一页多少条，不传递默认20条 |
|
|
|
|
|
|
|
|
|
|
2.2.3正常返回结果
|
返回键 |
类型 |
返回值 |
说明 |
|
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 } ] } } |
|||
2.2.4错误返回列表
详见：通用错误返回列表
三、操作类接口
3.1 新增操作
3.1.1接口说明
|
URL |
|
|
支持格式 |
JOSN |
|
HTTP请求方式 |
POST |
|
是否登录验证 |
|
|
请求数限制 |
|
3.1.2参数说明
|
参数名 |
必选 |
类型及范围 |
说明 |
|
xxx |
true |
String |
用户名 |
|
xxx |
true |
String |
|
|
xxx |
true |
String |
|
|
xxx |
true |
String |
|
|
|
|
|
|
3.1.3正常返回结果
|
返回键 |
类型 |
返回值 |
说明 |
|
result |
String |
结果代码信号 |
|
|
Response |
Object |
响应体 |
|
|
id |
int |
增数据的ID或者标志 |
|
|
text |
String |
操作提示语 |
如添加客户成功，可为空 |
|
{ “result”:”ok” , "Response": { "id": 1, "text": "" } } |
|||
3.1.4错误返回列表
详见：通用错误返回列表
3.2 修改操作
3.2.1接口说明
|
URL |
|
|
支持格式 |
JOSN |
|
HTTP请求方式 |
POST |
|
是否登录验证 |
|
|
请求数限制 |
|
3.2.2参数说明
|
参数名 |
必选 |
类型及范围 |
说明 |
|
xxx |
true |
String |
用户名 |
|
xxx |
true |
String |
|
|
xxx |
true |
String |
|
|
xxx |
true |
String |
|
|
|
|
|
|
3.2.3正常返回结果
|
返回键 |
类型 |
返回值 |
说明 |
|
result |
String |
结果代码信号 |
|
|
Response |
Object |
响应体 |
|
|
id |
int |
数据的ID或者标志 |
|
|
text |
String |
操作提示语 |
如修改客户成功，可为空 |
|
{ “result”:”ok” , "Response": { "id": 1, "text": "" } } |
|||
3.2.4错误返回列表
详见：通用错误返回列表
3.3 删除操作
3.3.1接口说明
|
URL |
|
|
支持格式 |
JOSN |
|
HTTP请求方式 |
POST |
|
是否登录验证 |
|
|
请求数限制 |
|
3.3.2参数说明
|
参数名 |
必选 |
类型及范围 |
说明 |
|
xxx |
true |
String |
用户名 |
|
xxx |
true |
String |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3.3.3正常返回结果
|
返回键 |
类型 |
返回值 |
说明 |
|
result |
String |
结果代码信号 |
|
|
Response |
Object |
响应体 |
|
|
id |
int |
数据的ID或者标志 |
|
|
text |
String |
操作提示语 |
如删除客户成功，可为空 |
|
{ “result”:”ok” , "Response": { "id": 1, "text": "亲，删除客户成功" } } |
|||
3.3.4错误返回列表
详见：通用错误返回列表
四、上传下载类
4.1 上传文件
4.1.1接口说明
|
URL |
|
|
支持格式 |
JOSN |
|
HTTP请求方式 |
POST |
|
是否登录验证 |
|
|
请求数限制 |
|
4.1.2参数说明
|
参数名 |
必选 |
类型及范围 |
说明 |
|
xxx |
true |
String |
用户名 |
|
xxx |
true |
File |
值为文件类型，处理同Web中的表单FILE一样 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
4.1.3正常返回结果
|
返回键 |
类型 |
返回值 |
说明 |
|
result |
String |
结果代码信号 |
|
|
Response |
Object |
响应体 |
|
|
filePath |
String |
文件存放的绝对路径 |
上传 |
|
|
|
|
|
|
{ “result”:”ok” , "Response": { "filePath": "http://www.baidu.com/logo.gif" } } |
|||
4.1.4错误返回列表
详见：通用错误返回列表
4.2 下载文件
4.2.1接口说明
|
URL |
|
|
支持格式 |
JOSN |
|
HTTP请求方式 |
POST |
|
是否登录验证 |
|
|
请求数限制 |
|
4.2.2参数说明
|
参数名 |
必选 |
类型及范围 |
说明 |
|
xxx |
true |
String |
文件网络绝对路径 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
4.2.3正常返回结果
|
返回键 |
类型 |
返回值 |
说明 |
|
|
|
|
确保文件可以正常访问下载 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|||
4.2.4错误返回列表
详见：通用错误返回列表
五、推送类接口
5.1 推送消息
5.1.1接口说明
|
URL |
|
|
支持格式 |
JOSN |
|
HTTP请求方式 |
POST |
|
是否登录验证 |
|
|
请求数限制 |
|
5.1.2参数说明
|
参数名 |
必选 |
类型及范围 |
说明 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
5.1.3正常返回结果
|
返回键 |
类型 |
返回值 |
说明 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|||
5.1.4错误返回列表
详见：通用错误返回列表
六、通用返回格式
6.1 正确返回
6.1.1接口说明
|
URL |
|
|
支持格式 |
JOSN |
|
HTTP请求方式 |
POST |
|
是否登录验证 |
|
|
请求数限制 |
|
6.1.2参数说明
|
参数名 |
必选 |
类型及范围 |
说明 |
|
xxx |
true |
String |
用户名 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
6.1.3正常返回结果
|
返回键 |
类型 |
返回值 |
说明 |
|
result |
String |
结果代码信号 |
|
|
Response |
Object |
响应体 |
|
|
|
|
|
|
|
|
|
|
|
|
{ “result”:”ok” , "Response": {
} } |
|||
6.1.4错误返回列表
详见：通用错误返回列表
6.2 错误返回
6.2.1接口说明
|
URL |
|
|
支持格式 |
JOSN |
|
HTTP请求方式 |
POST |
|
是否登录验证 |
|
|
请求数限制 |
|
6.2.2参数说明
|
参数名 |
必选 |
类型及范围 |
说明 |
|
xxx |
true |
String |
用户名 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
6.2.3正常返回结果
|
返回键 |
类型 |
返回值 |
说明 |
|
result |
String |
结果代码信号 |
|
|
Response |
Object |
响应体 |
|
|
errorText |
String |
错误信息 |
|
|
|
|
|
|
|
{ "result":"fail" , "Response": { "errorCode": -998 , "errorText": "用户名密码错误" } } |
|||
6.2.4错误返回列表
详见：通用错误返回列表
七、附录
7.1 通用错误返回列表
|
errorCode |
表示 |
说明 |
|
-999 |
通用错误 |
只用于一处，或者无关紧要的提示性，错误 |
|
-998 |
用户名密码错误 |
|
|
-997 |
用户登陆超时或别处登录 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
7.2 URL地址信息
7.2.1 主机地址
LocalHost正式地址：http://192.168.0.1/
LocalHost测试地址：http://192.168.0.1/
7.2.2 URL列表
|
URL |
描述 |
备注 |
|
API/login |
用户登录 |
无需验证 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
7.3 安全机制
7.3.1 验证签名机制
生成Token
7.4 其他
7.2.1 列表数据为空的返回
列表数据为空时显示 "DataList": []
如果对您有帮助 ，请多多支持.多少都是您的心意与支持，一分也是爱，再次感谢！！！