《移动开发接口及文档编写规范》V1.0

 

《移动开发接口及文档编写规范》V1.0文档说明

编写整理：童正刚 2015-05

一、概述

ü      有关接口

1、接口是纯数据的交互

APP接口是移动设备和业务之间进行通信的途径。实质就是以特定的规则通过接口直接操作数据库的增删改查。

 

 

ü      接口分类

1、查询类接口

查询类接口是指客户端传递一些参数，服务端根据参数依据需求，前往数据库查询需要的结果返回数据的一类接口。

返回类型一般有两种。第一种是返回一个对象，第二种是返回一个数组对象。

第一种比如登陆，客户端把用户名密码上传到接口，服务器返回用户的个人信息。

第二种比如获取客户，客户端把用户的身份信息上传到接口，服务器返回此身份下的所有客户数组集合。

 

2、操作类接口

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

 

3、上传下载类接口

上传下载类接口是涉及到文件传输的接口。比如上传头像，需要上传图片到服务器，服务端根据需求响应保存并返回结果。比如客户端需要显示用户头像，需要读取网络图片文件，在手机上进行显示。

 

4、推送类接口

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

二、接口编写原则

ü      实用性

编写接口API应遵从实用性原则。

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

 

2、接口执行效率（接口访问速度）：APP有别于WEB服务，对服务器端要求是比较严格的，在移动端有限的带宽条件下，要求接口响应速度要快，所有在开发过程中尽量选择效率高的框架，PHP推荐使用YAF框架，.NET推荐使用Newtonsoft

 

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

 

4、API缓存：这点比较重要&