APP接口开发规范文档-V1.0

1、页脚APP 接口规文档手机客户端接口文档文件状态：文件标识：草稿当前版本：1.0V正式发布作者：Stone正在修改完成日期：页脚版本历史版本/状态作者参与者起止日期V1.0/草稿Stone移动小组页脚目录一、概述11.1有关接口11.1.1接口是纯数据的交互11.2接口的分类11.2.1查询类接口11.2.2操作类接口11.2.3上传下载类接口11.2.4推送类接口1二、查询类接口格式规12.1获取单条对象信息12.1.1请求格式12.1.2参数说明22.1.3正常返回结果22.2获取列表对象信息32.2.1请求格式32.2.2参数说明32.2.3正常返回结果3三、操作类接口43.1新增操作4

2、3.1.1接口说明43.1.2参数说明43.1.3正常返回结果43.1.4错误返回列表53.2修改操作53.2.1接口说明53.2.2参数说明53.2.3正常返回结果53.2.4错误返回列表53.3删除操作63.3.1接口说明63.3.2参数说明63.3.3正常返回结果63.3.4错误返回列表6四、上传下载类74.1上传文件74.1.1接口说明74.1.2参数说明74.1.3正常返回结果74.1.4错误返回列表7页脚4.2下载文件74.2.1接口说明74.2.2参数说明84.2.3正常返回结果84.2.4错误返回列表8五、推送类接口85.1推送消息85.1.1接口说明85.1.2参数说明85.

3、1.3正常返回结果95.1.4错误返回列表9六、通用返回格式96.1正确返回96.1.1接口说明96.1.2参数说明96.1.3正常返回结果96.1.4错误返回列表106.2错误返回106.2.1接口说明106.2.2参数说明106.2.3正常返回结果106.2.4错误返回列表10七、附录117.1通用错误返回列表117.2URL地址信息117.2.1主机地址117.2.2 URL列表117.3安全机制117.3.1验证签名机制117.4其他127.2.1列表数据为空的返回12页脚一、概述一、概述1.1有关接口有关接口1.1.1接口是纯数据的交互接口是纯数据的交互APP接口是移动设备和业务之间

4、进行通信的途径。 实质就是以特定的规则通过接口直接操作数据库的增删改查。1.2接口的分类接口的分类1.2.1查询类接口查询类接口查询类接口是指客户端传递一些参数， 服务端根据参数依据需求， 前往数据库查询需要的结果返回数据的一类接口。返回类型一般有两种。第一种是返回一个对象，第二种是返回一个数组对象。第一种比如登陆，客户端把用户名密码上传到接口，服务器返回用户的个人信息。第二种比如获取客户，客户端把用户的身份信息上传到接口，服务器返回此身份下的所有客户数组集合。1.2.2操作类接口操作类接口操作类接口是指，客户端通过接口进行一些增删改的操作。比如新增一个客户，修改客户信息，或者删除一个客户。服

5、务器一般返回执行的状态，有的需要返回执行结果的一些信息，比如新增客户后，返回客户的ID。1.2.3上传下载类接口上传下载类接口上传下载类接口是涉及到文件传输的接口。比如上传头像，需要上传图片到服务器，服务端根据需求响应保存并返回结果。比如客户端需要显示用户头像，需要读取网络图片文件，在手机上进行显示。1.2.4推送类接口推送类接口除了客户端主动去请求服务端，获取需要信息之外。有时候，也存在服务端有消息需要通知客户端的情况，这时候就是服务端向客户端发送消息。这类需求可以通过客户端短时间类循环请求解决， 也可以通过第三方专业推送解决。 也可以通过自己使用socket或者xmpp等协议进行开发。二、

6、查询类接口格式规二、查询类接口格式规2.1获取单条对象信息获取单条对象信息2.1.1请求格式请求格式URL页脚支持格式JOSN页脚HTTP请求方式POST是否登录验证请求数限制2.1.2参数说明参数说明参数名必选类型及围说明XXXtrueString用户名2.1.3正常返回结果正常返回结果返回键类型返回值说明resultString结果代码信号ok结果成功，fail结果失败ResponseObject响应体Keylint响应字段值Key2String响应字段值Key3Object响应字段值可以依然包含对象体Key3Key1int响应字段值result:ok,Response:userName:

7、Mary,sex:1,Address:city:JiNan,county:LiXia2.1.4错误返回列表错误返回列表详见：通用错误返回列表页脚2.2获取列表对象信息获取列表对象信息2.2.1请求格式请求格式URL支持格式JOSNHTTP请求方式POST是否登录验证请求数限制2.2.2参数说明参数说明参数名必选类型及围说明XXXtrueString用户名Pagefalseint第几页，不传递默认第一页Sizefalseint一页多少条，不传递默认20条2.2.3正常返回结果正常返回结果返回键类型返回值说明resultString结果代码信号ResponseObject响应体LastUpdate

8、TimeString最后一条更新时间根据此时间判断新旧ThisPageNumberint当前页条数判断是否为空，是否有下页DataListArrayObject对象列表时间倒序排列“result”：”ok”,Response:LastUpdateTime:2012-12-1122:01:09,ThisPageNumber:2,DataList:id:1,date:2014-07-24,detail:,points:50,id:2,页脚date:2014-07-24,detail:,points:502.2.4错误返回列表错误返回列表详见：通用错误返回列表三、操作类接口三、操作类接口3.1新增操

9、作新增操作3.1.1接口说明接口说明URL支持格式JOSNHTTP请求方式POST是否登录验证请求数限制3.1.2参数说明参数说明参数名必选类型及围说明XXXtrueString用户名XXXtrueStringXXXtrueStringXXXtrueString3.1.3正常返回结果正常返回结果返回键类型返回值说明resultString结果代码信号ResponseObject响应体idint增数据的ID或者标志textString操作提示语如添加客户成功，可为空“result”：”ok”,Response:id:1,text:页脚3.1.4错误返回列表错误返回列表详见：通用错误返回列表3.2

10、修改操作修改操作3.2.1接口说明接口说明URL支持格式JOSNHTTP请求方式POST是否登录验证请求数限制3.2.2参数说明参数说明参数名必选类型及围说明XXXtrueString用户名XXXtrueStringXXXtrueStringXXXtrueString3.2.3正常返回结果正常返回结果返回键类型返回值说明resultString结果代码信号ResponseObject响应体idint数据的ID或者标志textString操作提示语如修改客户成功，可为空“result”：”ok”,Response:id:1,text:3.2.4错误返回列表错误返回列表详见：通用错误返回列表页脚3

11、.3删除操作删除操作3.3.1接口说明接口说明URL支持格式JOSNHTTP请求方式POST是否登录验证请求数限制3.3.2参数说明参数说明参数名必选类型及围说明XXXtrueString用户名XXXtrueString3.3.3正常返回结果正常返回结果返回键类型返回值说明resultString结果代码信号ResponseObject响应体idint数据的ID或者标志textString操作提示语如删除客户成功，可为空“result”：”ok”,Response:id:1,text:亲，删除客户成功3.3.4错误返回列表错误返回列表详见：通用错误返回列表页脚四、上传下载类四、上传下载类4.1

12、上传文件上传文件4.1.1接口说明接口说明URL支持格式JOSNHTTP请求方式POST是否登录验证请求数限制4.1.2参数说明参数说明参数名必选类型及围说明XXXtrueString用户名XXXtrueFile值为文件类型，处理冋Web中的表单FILE一样4.1.3正常返回结果正常返回结果返回键类型返回值说明resultString结果代码信号ResponseObject响应体filePathString文件存放的绝对路径上传“result”：”ok”,Response:filePath:.baidu./logo.gif4.1.4错误返回列表错误返回列表详见：通用错误返回列表4.2下载文件下载文件4.2.1接口说明接口说明URL页脚支持格式JOSNHTTP请求方式POST是否登录验证请求数限制4.2.2参数说明参数说明参数名必选类型及围说明XXXtrueString文件网络绝对路径4.2.3正常返回结果正常返回结果返回键类型返回值说明确保文件可以正常访问下载4.2.4错误返回列表错误返回列表详见：通用错误返回列表五、推送类接口五、推送类接口5.1推送消息推送消息5.1.1接口说明接口说明