BaaS API 设计规范

一、DDL

上个月写了四个团体中的 BaaS API 的设计规范,给大家分享下:

 1、DDL的概述

目录

      DDL(Data Definition Language
数据定义语言)用于操作对象和指标的特性,那种对象包蕴数据库自身,以及数据库对象,像:表、视图等等,DDL对这个目的和总体性的治本和定义具身体表面以后Create、Drop和Alter上。尤其注意:DDL操作的“对象”的概念,”对象“包涵对象及对象的属性,而且对象最小也比记录大个层次。以表举例:Create成立数据表,Alter可以改变该表的字段,Drop能够去除这些表,从那边大家能够看来,DDL所站的万丈,他不会对具体的多寡开始展览操作。

  1. 引言… 4

 

1.1. 概要… 4

2、DDL的要紧语句(操作)

1.2. 参阅资料… 4

      Create语句:可以创制数据库和数据库的某些目的。

1.3. 观望对象… 4

     
Drop语句:可以去除数据表、索引、触发程序、条件约束以及数据表的权位等。

1.4. 术语解释… 4

      Alter语句:修改数据表定义及品质。

  1. API 设计规范… 5

 

2.1. 地点格式… 5

③ 、 DDL的操作对象(表)

2.2. 输入与输出… 6

      1)、表的定义

2.2.1. 通用输入数据… 6

           
表的始建便是用来存放数据用的,由于大家存放的数据的不等,所以大家须要定义些数据类型,以方便管理。

2.2.2. 中央输入… 6

      2)、表的属性

2.2.3. 通用输出数据… 6

           
主键属性:主键正是主键约束,只不过起的名字不一致了,主键的起名偏向于虚的(正是讲述描述那件事),主键约束起名偏向于实得(正是讲述操作的推行),描述的都是一律件事,主键约束就是表中的一个天性;在多个表中最多可以有二个主键;1个主键能够定义在一个或多少个字段;主键使二个或四个字段的值必须唯一且不为空,那样做能够通过该字段或该组字段中的值唯一的表示一条记下。

2.2.4. 状态码… 7

           
唯一属性:2个表中只可以有2个主键属性,为了方表用户,建议唯一约束;唯一约束能够定义在二个或八个字段上;唯一约束使该字段或该组字段中的值唯一,能够为空,但是,不可能重复。

2.2.5. 可怜处理… 7

           
外键属性:又叫外键,又叫外键约束,跟主键和主键约束的关联是一致的;外键约束针对的七个表,如若表A的主关键字是表B中的字段,则该字段称为表B的外键,表A称为主表,表B称为从表,但要注意,必需要总括机要了然您是那种关涉。
            核对、Null和缺省属性:核对属性又叫查对约束,Null属性又叫Null约束,缺省属性又叫缺省约束;那一个名称是讲述一件事,描述一种情景,这件事或那张景况我们自然能够人工的那样特意做(输入数据是留意就行),不过,他们的本意是贯彻自动化,也正是让电脑做那件事。

2.2.6. 其它… 8

 

2.3. API操作设计… 8

二、DML

2.3.1. 财富型操作… 8

1、DML的概述

2.3.2. 业务型操作… 12

     DML(Data Manipulation Language
数据操控语言)用于操作数据库对象中蕴含的多寡,也正是说操作的单位是记录。

  1. API 扶助文书档案规范… 12

 

3.1. 援救文书档案内容规范… 12

贰 、DML的要害语句(操作)

3.2. 文书档案编写方法… 13

     Insert语句:向数据表张插入一条记下。

3.3. 扶持文书档案XML模板… 13

   
 Delete语句:删除数据表中的一条或多条记下,也足以去除数据表中的全数记录,不过,它的操作对象仍是记录。

     Update语句:用于修改已存在表中的笔录的情节。

1. 引言

 

1.1. 概要

BAAS 平台上的有着 API,必须严峻根据本标准。

透过本文书档案规范 BAAS 平台具有向外提供
API,显示技术的统一性、规范性。并使得全部 API
尽量靠近产业界规范的还要,升高API的易用性、可读性、包容性等,并有利于平台的使用者更快地窥见、熟悉全数API以供开发。

关键含有四个地点的正经:API 本身的设计规范、API 辅助文书档案的编辑规范。

③ 、DML的操作对象——记录

1.2. 参考资料

Representational State Transfer
(REST)

     1)、注意当大家对记录进行Insert、Delete和Update操作的时候,一定要注意,一定要明白DDL对其的有个别操作。

1.3. 观察对象

· 供给把 API 发布到BAAS 平马赛的全体开发者。

· 使用 BAAS API 的开发者。

 

1.4. 术语解释

Ø
BAAS:后端即服务。参见:《BaaS服务的概念、发展以及现在》。

Ø REST:一种开放的依据网络的软件架构情势。参见:《Representational
State Transfer
(REST)
》。

三、DCL

2. API设计规范

1、DCL的概述

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
组中幽微年龄二十九岁的用户。

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

其它表明:

Version 代表版本号,只有两级的版本号。

今非昔比的版本号之间,原则上能够不保险 API 的匹配。

某个版本一旦发表,在同一个版本号之内的 api 升级,必须保障包容原来发表的
API。不能够合作时,须求运用新的 API 地址,同时必须保留旧的 API。

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

     DCL(Data Control Language
数据控制语句)的操作是数据库对象的权力,这一个操作的规定使数码更是的平安。

2.2. 输入与出口

 

2.2.1. 通用输入数据

对此任何BAAS中各种 API 的调用都需求付出的数据,使用 Http Header
来展开传输。例如:App 授权码、用户标识 等新闻。

某些 Area 中山大学量 API都亟需交给的多少,也相应运用 Http Header
来展开提交。

二 、DCL的重点语句(操作)

2.2.2. 重点输入

考虑到接口的增加性,全部API的输入只好接受相似的 JSON
对象作为输入参数,同时也不得不输出一个 JSON 对象。

当输入输出的值是单纯值、数组时,须求运用2个目的对其展开包装。

富有 JSON 对象的属性名,全体采取首字母小写的驼峰式语法。

   
 格兰特语句:允许对象的创立人给某用户或某组或有所用户(PUBLIC)有个别特定的权杖。

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。

     Revoke语句:能够吐弃某用户或某组或具有用户访问权限

2.2.4. 状态码

动静码分为两类,1个是 Http 状态码;一个是 Result 数据结构中的
StatusCode 状态码。HTTP 状态码表示该 HTTP
请求的拍卖意况。一个伸手是还是不是中标是由 HTTP 状态码注明的. 3个 2XX
的状态码表示成功, 而二个 4XX 表示请求失利.

相似情形下,借使能使用 HTTP 状态码表示的情景,应该事先采用 HTTP
状态码。其次,BAAS 内部的种种业务逻辑状态,则应该由 StatusCode 来申明。

  1. 对于 HTTP 状态码而言,全数API近年来只行使以下状态码:

· 200:操作成功再次来到。

· 201:表示制造成功,POST 添加数码成功后务必回到此状态码。

· 400:请求格式不对。

· 401:未授权。(App、User)

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

· 500:内部程序错误。

里头,20壹 、404那个状态码,是索要API开发者在每叁个API中,依照作业逻辑的实践结果来主动重临的。别的的状态码由框架统一进行重临。

  1. StatusCode

StatusCode将统一选拔八个人编码,代表享有差别的事体逻辑分支。8位编码中的前两位代表不一致的Area
(模块),由BAAS平台合并标准。后二位由模块开发者自行定义。如:01表示ACS,那么0一千1可能意味着ACS模块中的登录API的用户名错误、0一千2代表ACS中的登录API的用户密码错误。

 

2.2.5. 特别处理

恳请战败重返 4XX 后,响应的主脑照旧是 Result 数据格式。个中 message
表示错误的音信。方便开展调节。如:

HttpStatusCode:404

Response Body:{success:false, statusCode:一千03,
message:’不设有该用户。’}

三 、DCL的操作对象(用户)

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.NET WebApi
框架搭建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 对象提交数据,该对象中包括1个属性名为
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 来开始展览呼吁。

· 此外查询

每1个独特查询,都亟待提供对应的特殊查询地址。必须参数以URubiconI Part
的款式提交,可选参数则以询问字符串的款型提交。例如,使用以下格式:

/users/username/hqf/minAge/30/?optionalParam1=1

万一多少个 API
使用了一样的参数,则须要在能源后增添2个查询的称谓,用以区分。如:

/users/find2/username/hqf/minAge/30/?optionalParam1=1

· OData 查询

规划建议:尽量不要提供OData查询。

设若要提供OData查询API,必须考虑查询的权力的范围,同时不要发表排序接口,不然质量只怕会很差。

· 查询能源的合集

有时,查询不是平昔指向有个别单一的能源,而是一道查询一名目繁多能源的合集,再次回到值的格式也与纯粹财富格式差异。这时,要求为这几个能源合集声美赞臣(Meadjohnson)个新的资源地址。例如,查询用户与剧中人物的合集,能够运用新的财富地址:/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 表明请求的点子、地址。

o UCRUISERI 参数:要是 U大切诺基I
中某部分是动态的,请使用大括号表明:api/values/{id}。

o U福睿斯I 查询参数:假诺 UEnclaveI
地址有参数,描述各项参数与认证。每一种参数是或不是可选。

o 请求标头:假设有异乎平常的呼吁标头,须要特地逐一表达。

· 响应

o 表达响应的状态码、内容格式。

o 响应标头:借使有分外的伸手标头,需求专门逐一表达。

o 响应正文:特殊字段、重点必须表达含义。尽量表达响应正文的享有字段意义。

· 可选:授权、备注

· 示例请求与响应

参考示例:

· MS Azure
文档示例

3.2. 文书档案编写方法

API开发者需求为其发表的每三个API建立一个XML文书档案用于详细描述上述的赞助内容。该文书档案建议以与API对应的点子名起名,方便寻找。文书档案的始末由联合的模版分明。

框架组提供联合的变换工具来扭转对应的 API 网页。最后会面并在方方面面 API
网站中。

3.3. 帮衬文书档案XML模板

该模板以附属类小部件方式提交。

 

文件下载地址:http://pan.baidu.com/s/1pJsswQJ

发表评论

电子邮件地址不会被公开。 必填项已用*标注

网站地图xml地图