Android开发规范：API接口通用设计规范

我的新书《Android App开发入门与实战》已于2020年8月由人民邮电出版社出版，欢迎购买。点击进入详情

API接口设计系列文章

1. Android开发规范：API接口安全设计规范
2. Android开发规范：API接口通用设计规范

通用规范

版本号

每一组API接口需要对应一个大版本号，大版本号一般是跟app的大版本对应的。
比如app第一版本我们叫v1，app第二版本经过改版后，接口返回内容一般也会有变化，我们叫v2。
以Restful API风格为例：
https://www.example.com/api/v{x}/，一般我们会在api接口的前面位置加上v{x}这个值。
x分两种情况：
1. 整型表示大版本号，比如v1、v2。
2. 浮点型表示小版本号，是对是大版本定义的业务接口的补充，比如v1.1。

举个例子：

1. https://www.example.com/api/v1/userinfo
   表示v1这个大版本的app，有一个userinfo业务类型的接口；
2. https://www.example.com/api/v2/userinfo
   表示v2这个大版本的app，同样有一个userinfo业务类型的接口；
3. https://www.example.com/api/v2.1/userinfo
   表示v2这个大版本中，userinfo这个业务接口进行了一些细微调整。

请求参数

请求参数由公共请求参数+业务请求参数组合而成。

1. 公共请求参数

参数名	参数类型	是否必填	描述
nonce	String	是	防重放攻击
timestamp	String	是	防重放攻击
sign	String	是	请求参数的签名
accessToken	String	否	鉴权标志，用于登录判断
appKey	String	是	防篡改
version	String	否	客户端版本号

其中version表示客户端版本号，此处将其传给服务器，由服务器根据客户端版本号进行一定的业务逻辑判断。

2)业务请求参数
以登录为例：

参数名	参数类型	是否必填	描述
name	String	是	姓名
password	String	是	密码

一个完整的URL如下（以传统URL格式为例）：

https://www.example.com/api/v1/getUserInfo.do?nonce=3ec934e8-81b9-492e-933d-a5dc41eb15bd&timestamp=1567118072&sign=c1741210c06f3827d1d2f3bfd1f1fc2878377307&accessToken=LvzFEeQSuU9B4DrnoPO9D4CL3ZhKCetZ%2FRckCWQlgb9qmNLmgCKxkymoC4pEs5LFw1lSAGZXKvHe%0AvpFgXKmAAQ%3D%3D&appKey=3b6af23db66c69b7131a8186f90fe663&name=jack&password=123456

返回值

使用Json格式（而不是XML）返回API请求结果。Json格式简洁，传输数据量小，而且能展示复杂的数据结构。

	{
	    "body":{
	    },
	    "code":0,
	    "msg":""
    }

code：API接口执行状态，比如0表示成功，-100表示网络超时，-200表示鉴权失败等等；
msg：非成功状态下，需要说明的信息，一般这个是服务器和code状态码一一对应定义；
body：返回的具体数据，也是Json格式。

客户端需要对所有code的值进行一一处理。

接口变更

一般来说一个API接口投入使用后，除非这个接口确定废弃不再使用，一般情况下不能对这个接口进行修改，比如API的请求参数和返回值，否则会对使用此API接口的APP带来不可预估的影响，最严重的就是崩溃。

如果接口需要变更，那我们需要保证API接口的变更能够向下兼容，就是API的变更不影响原有使用API接口的客户端。

如果不能够保证向下兼容，那么只有新建新的API接口。

接口变更有以下两种情况：能够向下兼容、不能兼容需要新建新的API接口。

以下是一个原始的json格式的返回值：

{
  "id": 1,
  "name": "jack",
  "address": "usa"
}

原始URL：https://www.example.com/api/v1/userinfo

1. 向下兼容
   (1)url的请求参数新增字段，比如
   https://www.example.com/api/v1/userinfo?currentTime=2019/12/12
   新增一个请求参数currentTime，不影响当前API接口的使用。
   (2)url的返回数据结构增加字段，比如：

{
  "id": 1,
  "name": "jack",
  "address": "usa"
  "age": 18
}

增加一个age字段，旧版本app只会需要id、name、address三个字段，多出来的age字段对它们来说没有用处，也不会额外处理。而新版本的app使用到这个接口时，可以对这四个字段进行解析，将新增加的age字段利用起来。

2. 新建新的API接口
   如果返回的数据格式字段值类型发生了变化，比如age原先是数字类型，值为18，现在改为字符串类型，值为“18”，这样旧版本解析的时候可能就会出错，影响使用。

{
  "id": 1,
  "name": "jack",
  "address": "usa"
  "age": "18"
}

或者直接将age这个字段的名称改变了，变成year；或者直接将age这个字段给删除掉了。
这些情况对当前使用这个api的app来说一定会产生影响，所以如果出现这种情况需要新增一个新的接口，而不是在原有的接口上修改。

API格式

传统格式

示例：

https://www.example.com/getUserInfo.do?id=10000&netType=wifi

API通过具体的业务地址（getUserInfo.do）和请求参数（id=10000&netType=wifi）拼装而成。

请求类型一般就get和post两种，而且有时候在实际项目中这两种类型的请求并没有区分的很明细，而是都可以使用。

RestFul API

示例：
https://www.example.com/api/v1/userinfo
Restful API通过URI（如api/vi/userinfo）来表示资源，通过HTTP GET、POST、PUT、DELETE等方法表示操作行为。
GET：获取资源；
POST：新建资源；
PUT：更新资源；
DELETE：删除资源；

URI一般使用名词命名，比如GET /userinfo，表示获取全部用户的信息；GET /userinfo/100表示获取id为100的用户信息。