上个月写了一个团队中的 BaaS API 的设计规范，给大家分享下：

目录

1. 引言... 4

1.1. 概要... 4

1.2. 参考资料... 4

1.3. 阅读对象... 4

1.4. 术语解释... 4

2. API 设计规范... 5

2.1. 地址格式... 5

2.2. 输入与输出... 6

2.2.1. 通用输入数据... 6

2.2.2. 主体输入... 6

2.2.3. 通用输出数据... 6

2.2.4. 状态码... 7

2.2.5. 异常处理... 7

2.2.6. 其它... 8

2.3. API操作设计... 8

2.3.1. 资源型操作... 8

2.3.2. 业务型操作... 12

3. API 帮助文档规范... 12

3.1. 帮助文档内容规范... 12

3.2. 文档编写方法... 13

3.3. 帮助文档XML模板... 13

1. 引言 1.1. 概要

BAAS 平台上的所有 API，必须严格遵守本规范。

通过本文档规范 BAAS 平台所有向外提供 API，体现技术的统一性、规范性。并使得所有 API 尽量靠近业界规范的同时，提高API的易用性、可读性、兼容性等，并方便平台的使用者更快地发现、熟悉所有API以供开发。

主要包含两个方面的规范：API 本身的设计规范、API 帮助文档的编写规范。

1.2. 参考资料

《Representational State Transfer (REST)》

1.3. 阅读对象

· 需要把 API 发布到BAAS 平台中的所有开发者。

· 使用 BAAS API 的开发者。

1.4. 术语解释

? BAAS：后端即服务。参见：《BaaS服务的定义、发展以及未来》。

? REST：一种开放的基于互联网的软件架构模式。参见：《Representational State Transfer (REST)》。

2. API 设计规范 2.1. 地址格式

对于发布的所有 API，地址应该满足以下格式：

· 格式一，直接访问资源型：

/api/v(version)/area/resources/{id}

· 格式二，资源查询型：

/api/v(version)/area/resources/param1Name/param1Value/param2Name/param2Value/?optionalParameters

· 格式三，资源操作型、跨资源业务型：

/api/v(version)/area/resources or controller/action?parameters

示例：

/api/v1.0/acs/users/ 表示访问所有的用户资源。

/api/v1.0/acs/users/1 表示访问 Id 为 1 的用户。

/api/v1.0/acs/users/group/iws-tech/minAge/30 表示访问 iws-tech 组中最小年龄30岁的用户。

/api/v1.0/acs/accounts/UpdateAllUserFlags 表示更新所有用户的某个标识。

其它说明：

Version 表示版本号，只有两级的版本号。

不同的版本号之间，原则上可以不保证 API 的兼容。

某个版本一旦发布，在同一个版本号之内的 api 升级，必须保证兼容原来发布的 API。不能兼容时，需要使用新的 API 地址，同时必须保留旧的 API。

Area 表示某个业务模块，如 ACS、Org、OneDoc、OnePlus 等。

2.2. 输入与输出 2.2.1. 通用输入数据

对于整个BAAS中每一个 API 的调用都需要提交的数据，使用 Http Header 来进行传输。例如：App 授权码、用户标识 等信息。

某个 Area 中大量 API都需要提交的数据，也应该使用 Http Header 来进行提交。

2.2.2. 主体输入

考虑到接口的扩展性，所有API的输入只能接受一般的 JSON 对象作为输入参数，同时也只能输出一个 JSON 对象。

当输入输出的值是单一值、数组时，需要使用一个对象对其进行封装。

所有 JSON 对象的属性名，全部使用首字母小写的驼峰式语法。

2.2.3. 通用输出数据

对于 CDU 以及修改数据为主的操作型API的响应，都必须返回一个统一的数据格式 Result，该结构定义如下：

{ success: boolean, statusCode: int, message: string, data: object }

其中：

success：表示该操作是否成功。

statusCode：该操作如果有多种返回的状态，使用statusCode进行区分。一般情况下，statusCode 返回1或0表示成功或失败。该属性用于给开发者进行程序分支的逻辑判断使用。

message：总是返回一个可用于客户端显示的字符串。该属性用于显示给软件使用者查看。

data是可选属性。即如果没有额外的数据，可以没有data属性，也可以data 返回 null。

2.2.4. 状态码

状态码分为两类，一个是 Http 状态码；一个是 Result 数据结构中的 StatusCode 状态码。HTTP 状态码表示该 HTTP 请求的处理状态。一个请求是否成功是由 HTTP 状态码标明的. 一个 2XX 的状态码表示成功, 而一个 4XX 表示请求失败.

一般情况下，如果能使用 HTTP 状态码表示的状态，应该优先使用 HTTP 状态码。其次，BAAS 内部的各种业务逻辑状态，则应该由 StatusCode 来标明。

1. 对于 HTTP 状态码而言，所有API暂时只使用以下状态码：

· 200：操作成功返回。

· 201：表示创建成功，POST 添加数据成功后必须返回此状态码。

· 400：请求格式不对。

· 401：未授权。（App、User）

· 404：请求的地址未找到。如 users/1 未找到该资源。

· 500：内部程序错误。

其中，201、404这两个状态码，是需要API开发者在每一个API中，根据业务逻辑的执行结果来主动返回的。其它的状态码由框架统一进行返回。

2. StatusCode