BAAS API 设计规范精.docx

BAAS API 设计规范精.docx

《BAAS API 设计规范精.docx》由会员分享，可在线阅读，更多相关《BAAS API 设计规范精.docx（10页珍藏版）》请在冰豆网上搜索。

BAASAPI设计规范精

1.引言

1.1.概要

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

通过本文档规范BAAS平台所有向外提供API，体现技术的统一性、规范性。

并使得所有API尽量靠近业界规范的同时，提高API的易用性、可读性、兼容性等，并方便平台的使用者更快地发现、熟悉所有API以供开发。

主要包含两个方面的规范：

API本身的设计规范、API帮助文档的编写规范。

1.2.参考资料

1.3.阅读对象

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

∙使用BAASAPI的开发者。

1.4.术语解释

ØBAAS：

后端即服务。

Ø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/resourcesorcontroller/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的调用都需要提交的数据，使用HttpHeader来进行传输。

例如：

App授权码、用户标识等信息。

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

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

StatusCode将统一使用6位编码，代表所有不同的业务逻辑分支。

6位编码中的前两位代表不同的Area（模块），由BAAS平台统一规范。

后四位由模块开发者自行定义。

如：

01表示ACS，那么010001可能表示ACS模块中的登录API的用户名错误、010002表示ACS中的登录API的用户密码错误。

2.2.5.异常处理

请求失败返回4XX后，响应的主体依然是Result数据格式。

其中message表示错误的信息。

方便进行调试。

如：

HttpStatusCode:

404

ResponseBody:

{success:

false,statusCode:

100003,message:

'不存在该用户。

'}

2.2.6.其它

时间的格式：

API返回值中的时间，都统一采用UTC格式时间。

API的返回值中，如果需要包含调试相关信息（如调用时间、调用次数等），由BAAS平台框架统一处理，不单独在各API中处理。

2.3.API操作设计

每个具体的API地址，都是一个操作。

操作分为两种类型：

资源型操作、业务型操作。

2.3.1.资源型操作

资源型操作是满足REST规范化设计的。

在设计API时，应尽量首选这种模式。

即：

如果API能抽象为资源的CRUD操作的，应该尽量先抽象为对资源的操作。

2.3.1.1.添加

地址：

资源列表地址。

如/users/。

使用POST动作提交实体对应的JSON格式数据。

2.3.1.2.更新

地址：

具体某个资源的地址。

如/users/1，表示id为1的用户。

动作：

使用PUT动作提交。

数据格式：

实体的JSON格式数据。

其中，JSON数据中不需要列全所有的属性，只需要列出需要更新的属性即可。

如：

PUT/users/1{username:

'hqf'}。

对应的响应是：

HttpStatusCode:

200

ResponseBody：

{success:

true,statusCode:

1,message:

'更新成功！

'}

（另：

如果使用ASP.NETWebApi框架搭建API，则这里需要提供统一的框架处理此类型的反序列化。

）

2.3.1.3.删除

地址：

具体某个资源的地址。

如/users/1。

动作：

使用DELETE动作提供请求。

如：

DELETE/users/1

对应的响应是：

HttpStatusCode:

200

ResponseBody：

{success:

true,statusCode:

1,message:

'删除成功！

'}

2.3.1.4.批量保存

设计建议：

尽量不要为每一个资源提供批量保存的操作。

只有在对资源的操作的性能要求较高时，才选择性提供。

地址：

资源列表地址。

如/users/。

动作：

使用POST动作提供数据。

数据格式：

使用一个JSON对象提交数据，该对象中包含一个属性名为list，属性类型为数组的属性。

该数组中的每一个对象都是要更新的实体对象。

对于每一个实体对象：

可以为每一个子实体对象添加persistenceStatus属性，值为Deleted、Modified、New来表示该实体的状态：

删除、更新、添加。

如果不提供该属性，那么如果实体有Id属性，则表示更新，否则表示添加。

例如：

{list:

[

{name:

'c1',persistenceStatus:

'New'},

{id:

1,name:

'c2',persistenceStatus:

'Modified'},

{id:

2,persistenceStatus:

'Deleted'}

]}

也可省略为：

{list:

[

{name:

'c1'},//添加

{id:

1,name:

'c2'},//更新

{id:

2,persistenceStatus:

'Deleted'}

]}

2.3.1.5.保存聚合子

设计建议：

在需要更新聚合子实体时，如果公布了聚合子资源API，那么应该首选这个资源来实现保存。

否则，才可以在更新聚合父实体时，同时更新它的聚合子实体。

地址与动作：

保存聚合子使用聚合父资源相同的地址和动作，见：

更新。

数据格式：

聚合父对象中有聚合子对应的属性，该属性使用批量更新中定义的数据格式来定义需要更新的聚合子实体集合。

见：

批量保存。

如：

{name:

'parent',children:

[

{name:

'c1',persistenceStatus:

'New'},

{id:

1,name:

'c2',persistenceStatus:

'Modified'},

{id:

2,persistenceStatus:

'Deleted'}

]}

也可省略为：

{name:

'parent',children:

[

{name:

'c1'},

{id:

1,name:

'c2'},

{id:

2,persistenceStatus:

'Deleted'}

]}

2.3.1.6.查询

∙查询所有资源

地址：

资源列表地址。

如：

/users/。

动作：

使用GET来进行请求。

∙查询指定id的资源

地址：

资源地址+Id。

如：

/users/1。

动作：

使用GET来进行请求。

∙其它查询

每一个特殊查询，都需要提供相应的特殊查询地址。

必须参数以URIPart的形式给出，可选参数则以查询字符串的形式给出。

例如，使用以下格式：

/users/username/hqf/minAge/30/?

optionalParam1=1

如果两个API使用了相同的参数，则需要在资源后追加一个查询的名称，用以区分。

如：

/users/find2/username/hqf/minAge/30/?

optionalParam1=1

∙OData查询

设计建议：

尽量不要提供OData查询。

如果要提供OData查询API，必须考虑查询的权限的限制，同时不要公布排序接口，否则性能可能会很差。

∙查询资源的合集

有时，查询不是直接针对某个单一的资源，而是联合查询一系列资源的合集，返回值的格式也与单一资源格式不同。

这时，需要为这个资源合集声明一个新的资源地址。

例如，查询用户与角色的合集，可以使用新的资源地址：

/userRoles/。

2.3.2.业务型操作

业务型操作表示可能跨越多个资源的逻辑操作。

服务器端直接提供的服务。

∙一般只使用POST动作，偶尔使用GET动作。

不能使用PUT、DELETE动作。

∙Action不要使用简单的、通用的名称。

如不要使用与资源操作冲突的Get、Add、Update、Delete、Save等名称。

而使用具体的逻辑名称，如transfer、refreshTag等……

∙推荐放到单独的服务地址（控制器）中。

如：

POST/{transaction}/{transfer}{from:

'a',to:

'b',money:

10}。

∙如果只是对某个资源单独的操作，那么也可以放在该资源地址下。

如：

POST/users/refreshLogoutTime。

;

3.API帮助文档规范

BAAS平台中的API帮助文档将采用统一的格式编写，并以HTML页面的形式发布。

帮助文档使用以下地址：

GET/api/v1.1/返回1.1版本API的帮助文档首页。

3.1.帮助文档内容规范

向外公布的每个API的帮助说明，必须至少包含以下几项：

∙API简介

∙请求

o说明请求的方法、地址。

oURI参数：

如果URI中某部分是动态的，请使用大括号说明：

api/values/{id}。

oURI查询参数：

如果URI地址有参数，描述各项参数与说明。

每个参数是否可选。

o请求标头：

如果有特殊的请求标头，需要特别逐一说明。

∙响应

o说明响应的状态码、内容格式。

o响应标头：

如果有特殊的请求标头，需要特别逐一说明。

o响应正文：

特殊字段、重点必须说明含义。

尽量说明响应正文的所有字段意义。

∙可选：

授权、备注

∙示例请求与响应

参考示例：

∙MSAzure文档示例

3.2.文档编写方法

API开发者需要为其公布的每一个API建立一个XML文档用于详细描述上述的帮助内容。

该文档建议以与API对应的方法名起名，方便查找。

文档的内容由统一的模板确定。

框架组提供统一的转换工具来生成相应的API网页。

最终会集成在整个API网站中。

3.3.帮助文档XML模板

该模板以附件形式给出。