3.3 应用API规范设计向导

用户创建并保存应用后，“编辑应用”页面中会显示新创建的应用的基本信息。此时用户可以通过点击右侧的“编辑规范”连接进入 API 规范设计向导。

在应用 API 规范设计向导中，用户可以通过一个五步的向导过程为自己的云端 应用制定 API 规范。这五步分别是:

1. 编辑应用基本信息
2. 添加应用内包含的服务和服务内包含的API信息
3. 填写API数据字段定义
4. 浏览和审阅API规范
5. 自动生成应用的框架代码

用户在完成以上的应用 API 规范设计后，便可从向导中自动生成的应用框架代码开始开发和调试自己的云端应用。以下简要介绍 API 规范设计向导的使用方法。

3.3.1 编辑应用基本信息

在点击“编辑规范”连接后，用户可以进入编辑规范向导页面，在向导的第一步中，用户可以继续审阅和编辑刚才在创建应用时填写的设备名称、制造商名称、应用说明等基本信息。

在基本信息编辑完成后，用户可以点击下方的“下一步”连接进入向导第二步。

3.3.2 添加服务和API信息

在向导第二步中，用户可以为应用添加各项服务，以及每个服务下的 API 名称，如以下截图所示:

用户可以在该页面的树状控件中中定制自己的应用下各个服务的名称，以及服务下的 API 名称。

应用下的各个服务以下格式命名:

urn:[命名空间前缀]-[命名空间后缀]:serviceID:[服务名称]

用户可以在 命名空间前缀 和 命名空间后缀 选项中填写自己企业或组织的域名前缀和后缀。在服务名称选项中填写服务的名称。命名空间前缀 和 命名空间后缀 选项需要输入英文字符，而 服务名称 可以选择填写中文或英文字符。

在服务名称信息填写完成后，用户可以继续输入该服务下 供的 API 的名称。 API 没有命名空间的前后缀，用户可以使用中文或英文作为 API 的名称。 在向导第二步中，用户可以为应用添加更多的服务，以及某个服务下更多的 API 信息。在页面的树状控件上，右键点击服务列表选项上便可在菜单中添加新的服务，如下图所示

右键点击已有的服务名称可为该服务添加新的 API，如下图所示:

3.3.3 设置应用限流信息

在向导第二步的树状控件中，用户可为服务应用定义每秒调用次数上限次数信息。如下图所示:

设置该信息并完成应用部署后，系统将在对该应用的每秒 API 调用请求超过指定的上限时自动拒绝对该服务应用的访问并返回相应的错误信息。

3.3.4 设置API日志和缓存时间标志

在向导第二步的树状控件中，用户可为服务应用中包含的 API 设置详细日志和缓存时间标志。

当用户设置 API 详细日志标志，并成功部署应用后，系统将记录该 API 调用的所有详细信息，包括输入参数数据、返回结果数据、响应时间、错误信息等。

当用户设置缓存时间长短标志，并成功部署应用后，系统将在设定的时间段内缓存该 API 调用上的所有数据，并储存在系统缓存数据库中。在该时间段内发生的 API 调用如果在缓存数据库中查到到重复的输入参数，将从缓存数据库中直接返回数据而不会将调用请求发送到应用代码处理。数据缓存能力可以帮助提高系统的整体吞吐能力，同时降低后台应用的处理压力。

当用户在向导第二步中右键点击添加的 API 名称时，系统弹出菜单允许用户定义该 API 是否需要记录详细日志，如下图所示。不输入该选项时，系统缺省不记录 API 详细日志。

用户点击“设置详细日志”选项后，系统弹出如下对话框供用户选择是否记录详细日志选项。用户选择后即可添加相应的详细日志选项

用户点击“设置缓存时间”选项后，系统弹出如下对话框供用户输入以毫秒 ms 为单位的缓存时间的长短。用户输入后即可添加相应的缓存时间选项

在应用所有的服务和 API 信息填写完成后，用户可点击右下方的“下一步”按钮进入应用 API 规范设计向导第三步。如下图所示:

3.3.5 填写API数据字段定义

在应用 API 规范设计向导第三步中，用户将看到以下的 JSON 编辑器界面:

当用户进入向导第三步时，系统将自动生成用于描述应用 API 规范的两个JSON 文件:api.json 和 schema.json，并提供对这两个 JSON 文件的在线编辑能力。其中，api.json 文件包含来自向导前两步中用户填写的信息，即应用的名称、开发厂商、简要说明等基本信息，以及应用中各个服务，以及服务下各个 API 的名称定义。schema.json 文件提供每个服务，以及服务下各个 API 中的参数、返回结果、错误信息等数据字段的定义。

在用户进入向导第三步时，api.json 中已经包含了前两步中输入的所有信息。通常情况下，在这一步中用户不需要改动左侧 api.json 文件的内容，只对右侧的 schema.json 的内容进行编辑，为其添加每个 API 的参数、返回结果等数据字段的内容即可。

在api.json和schema.json的编辑菜单中，用户可点击字段左侧的图标展开编辑菜单，如以下截图所示:

当用户点击字段左侧的图标并拖动该字段，可以将该字段以及之下的所有内容安放到 JSON 文件中的其他地方。如以下截图所示:

3.3.6 schema.json编辑器介绍

在平台系统网站上，用户可在 schema.json 编辑器中方便地添加应用下各个 API 的 JSON 格式参数、返回值以及错误信息的定义。schema.json 文件的内容为 API 上传输的 JSON 数据提供数据中各个字段的名称、类型、取值范围、缺省值等信息的定义。用户在 schema.json 中输入的对象和其下各个字段类型等定义将被系统用作 API 输入数据和返回结果的数据校验，并在不符合 schema.json 中提供的定义时给客户端返回相应错误提示，更好地过滤非法数据，并提高应用的健壮性。当前，平台的 schema.json 编辑器提供对 JSON schema draft-04 规范的支持。

本节以下内容介绍 shema.json 编辑器的使用方法。在开始阅读以下章节前，用户可参考 json-scheme.org 上对 JSON schema 规范的介绍，以帮助更好地理解和使用 schema.json 编辑器。

3.3.6.1 背景内容介绍

在实际使用中，客户端对部署在平台的云端应用发起的 API 调用格式如下:

请求 JSON 数据:
{
    "serviceID": <id>,
    "actionName": <name>,
    "input": { ... }
}

云端应用返回的响应数据格式如下:

响应 JSON 数据:
{
    "output": { ... }
}

当 API 调用出现错误时，错误信息以以下 JSON 格式返回:

返回错误 JSON 消息:
{
    "fault": { ... }
}

用户在 schema.json 文件填写的内容定义了以上 input, output, 和 fault JSON 对象的类型(数组或对象)，以及其中各个数据字段的名称、类型、取值范围等信息。用户在 schemea.json 文件中填写的内容将被平台读取，并基于该内容提供自动化的 JSON 数据完整性校验、API 文档自动生成、测试工具表单生成等功能。

3.3.6.2 使用方法介绍

当用户创建了一个新设备后第一次进入 schema.json 编辑器时，可以看到以下这样的空白模板:

如上图所示，某个 API 的输入参数、返回结果和错误信息都记录在以服务名称命名的 JSON 对象，以及其下的，以 API 名称命名的 JSON 对象中。API 的 JSON 格式输入参数和返回结果分别以 input 对象和 output 对象表示。API 的 JSON 格式的错误信息以 fault 对象表示。

在缺省的空白模板中，input 字段，output 字段以及 fault 字段都默认以对象类型表示。对 JSON schema 语法熟悉的用户，可以将其定义修改为其他类型，例如数组类型。

以下各节介绍编辑器中各项功能菜单的使用方法。

3.3.6.3 为输入参数和返回结果设置属性

当用户点击input对象或output对象所在行左侧的图标时，系统会显示以下的菜单，用户可以在这里为 input 对象或 output 对象设置其属性，属性包括 input 或 output 对象的标题、描述、必填项等。

如下图所示，在用户点击“设置属性”菜单中的“标题”选项后，系统会为 input 或 output 对象添加一个名称为 title 的字段。用户可在该字段中输入内容，例如“输入参数的标题”。这里表明该字段(input 对象)的标题是一个输入参数。

类似以上步骤，用户可以在编辑器中输入 input 或 output 对象的具体描述信息。如下图所示:

3.3.6.4 为输入参数和返回结果添加字段

当用户点击input对象或output对象中properties字段所在的行左侧的图标时，系统会弹出添加字段菜单。用户可以点击“添加字段”为 input 对象或 output 对象添加其下的字段，如下图所示:

点击“添加字段”选项后，编辑器会在当前的 properties 字段下生成一个新的空白对象，该对象代表 input 对象下的某个字段定义。用户为该对象填写的名称即代表该字段的名称。如下图所示:

在此处，用户填写的名称 foo 代表 input JSON 对象中包含一个名称为 foo 的字段。

用户可重复以上步骤，点击 properties 字段左侧的菜单，为 input 或 output 对象添加更多字段，此处不再一一列举。以下章节分别介绍为这些添加的字段设置标题、描述、类型、取值范围等信息的方法。

3.3.6.5 为字段添加类型信息

当用户点击某个字段所在的行左侧的图标时，系统会弹出以下的菜单供用户选择该字段的类型定义，对于 JSON 数据，系统支持四种基本的 JSON 变量类型:对象、数组、字符串和数值。用户可以根据自身的在 API 上传输的数据字段定义选择其中任意一种。

举例而言，当用户点击“字符串”选项，并设定 foo 字段为字符串类型时，编辑器会为 foo 字段添加以下的类型信息:

从下一节开始，本文介绍对对象、数组、字符串和数值等 4 种变量字段类型的设置方法。

3.3.6.6 字符串类型字段设置

对于字符串类型的字段，用户可点击该字段左侧的图标设置该字段的最小长度、最大长度、正则表达式等信息。如下图所示:

举例而言，在下图中，用户设置了 foo 字段的字符串取值最小长度为 2，最大长度为 10，同时必须满足 ^[0-9]$ 正则表达式的要求，也就是一个只包含数字 0 到 9 的字符串。

在编辑器中，用户也可以不输入正则表达式、最大长度、最小长度等条件定义，编辑器允许输入这些条件中的任意一种或完全不输入，系统会在真实 API 调用时对设置的任意一种条件做相应的数据校验。

3.3.6.7 数值类型字段设置

对于字符串类型的字段，用户可点击该字段左侧的图标设置该字段的最小值和最大值的取值范围信息。如下图所示:

数值类型同时包含对整数类型和浮点类型的定义。用户可以在最小值和最大值条件中输入整数类型或浮点类型的取值。

举例而言，在下图中，用户设置了 foo 字段为数值类型，并设置其最大值为 100，最小值为 33.3。

同字符串类型的字段定义相似，系统会根据用户设置的条件，在真实 API 调用时对设置的取值范围做相应的数据校验。

3.3.6.8 对象类型字段设置

对于对象类型的字段，用户可以使用以上介绍的 input 对象的编辑方法向其中添加字段和相应类型、取值范围等信息。此处不再复述。

3.3.6.9 数组类型字段设置

在用户设置数组类型的字段后，用户可以点击该字段左侧的图标，并点击 “设置属性”菜单，然后为其添加其成员的类型定义。如下图所示:

在点击“成员”选项后，编辑器会在该字段定义下生成以下的 items 字段定义: 点击items字段左侧的图标时，系统会显示如下变量类型设置菜单:

在弹出的数组成员类型设置菜单中，用户可以设置数组内成员变量的类型。例如，在下图中，用户设置了数组内成员为对象类型，对象中有 name 和 value 等两个字符串类型的字段:

在设置数组成员的类型后，用户可继续按照以上介绍的内容，对该类型的数据添加取值范围等条件，此处不再复述。

在 JSON schema 规范中，数组成员定义 items 可以是一个合法的 schema(对象类型)，也可以是一组合法的 schema(数组类型)，当 items 包含一组合法的 schema 定义时，相应 JSON 数据中每个成员都要符合这一组 schema 中的每个 schema 的规范约定。此处为简化系统设计，编辑器缺省定义 items 为一个合法的 schema(对象类型)，数组中每个成员变量都要符合该 schema 的规范定义。 对 JSON schema 规范熟悉的用户，可以在以下的向导第四步中自由定义 items 的类型和内容，包括将其改变成数组类型，为其添加更多合法的 schema 定义等。

3.3.6.10 添加必填字段信息

当用户点击input对象或output对象所在的行左侧的图标时，并点击“添加必填项”选项时，编辑器允许用户设置 input 对象或 output 对象中必填字段的名称。

在用户点击“添加必填项”选项后，编辑器会在 input 对象下生成一个名为 required 的空数组。如下图所示:

在创建 required 数组后，用户可点击其左侧的图标，选择“添加成员”选项，向 required 数组中添加成员。如下图所示:

required 数组中的元素全部是字符串，其取值为 input 对象下各个字段的名称。例如，要将以上的 foo 字段成为 input 对象的必填项，用户可选择“添加成员”后并输入 foo，如下图所示:

根据 JSON schema 规范的定义，没有列入 required 数组的字段全部都是选填项。

3.3.6.11 为字段添加标题和描述信息

对于任意类型的字段，用户都可以通过点击其左侧的图标，打开“设置属性” 菜单，设置该字段的标题和描述信息。例如，对于以上添加的 input 对象下的foo 字段，用户可以在菜单中设置其标题和详细描述信息，如以下截图所示:

在平台提供的应用测试工具中，用户在 API 设计向导中填写的字段标题和描述分别会出现在该字段的上方和下方，供使用者方便直观地了解各个字段的含义并填入相应测试数据。如下图所示:

3.3.6.12 嵌套字段定义

对于对象类型的字段，用户可以使用与上面介绍的 input 字段类似的方法为其中的各个子字段添加更多信息。

3.3.6.13 设置字段枚举值和缺省值信息

对于字符串类型和数值类型的变量，用户可以在字段左侧的编辑菜单中选择“添加”下拉菜单，为该字段设置枚举值和缺省值。如下图所示:

在点击枚举值菜单后，编辑器会在当前字段定义下添加 enum 数组，用户可在左侧编辑菜单中选择“添加成员”为该数组添加成员变量，其取值为该字段的枚举值。如下图所示:

类似地，用户在编辑器左侧的编辑菜单中选择“添加”下拉菜单，点击“缺省值”选项后，为字段设置缺省值，如下图所示:

在用户为某个 input 对象中某个字段设置枚举值后，平台提供的应用测试工具会自动为用户设定的枚举值生成下拉框测试表单，例如，以下的 input 对象下 foo 字段的 enum 定义:

会在应用测试工具中自动生成如下的表单:

3.3.6.14 为 API 添加错误信息

当用户创建新应用并进入 API 规范设计向导的 schema.json 编辑器时，系统会为应用的 API 生成以下的缺省错误信息定义模板:

在以上错误信息定义中，当前应用所有的 API 错误信息都存放在 schema.json 根节点的 fault 字段下，某个 API 的错误信息存放在其服务名称以及之下的 API 名称的 fault 字段中。

如以上截图所示，fault 字段的缺省定义是一个 JSON 对象，其中有两个字符串类型的属性字段。其名称分别是 reason 和 info。在对应用的 API 调用发生错误时，reason 字段的取值为错误的具体原因，info 字段的取值包含了错误的更进一步的详细信息。

例如，使用缺省的 fault 字段定义时，对应用的 API 调用出现错误时，错误信息会返回 HTTP 500 错误代码，并包含以下 JSON 格式的返回结果:

返回错误 JSON 消息:
{
    "fault": {
      "reason":"data validation failed",
      "info":"require field foo missing"
} }

如果用户需要对 API 的定义提供更多错误信息，可以编辑当前 API 的 fault 字段并添加新的字段定义。其定义方法和以上介绍的字段编辑方法相同，此处不再复述。

3.3.6.15 删除字段

用户可点击任意字段左侧的图标，选择“删除”选项，删除该字段以及其下下所有的内容，如以下截图所示:

3.3.7 审阅API规范

在用户结束对 API 规范和 API 数据字段，也就是 api.json 和 schema.json 的编辑后，可以点击应用 API 规范设计向导右下方的下一步图标进入向导第四步，审阅 API 规范页面:

进入审阅 API 规范页面后，用户将看到以下的 JSON 文件编辑界面:

在这里，api.json和schema.json已经包含了向导前三步中用户输入的所有信息，包括应用中的API以及他们的数据字段定义。通常情况下，在这里用户不需要对这两个文件做进一步编辑便可直接点击右下方的下一步按钮进入向导最后一步。但是，对JSON schema规范熟悉的用户可以继续自由地定义schema.json文件中的内容，例如，为字段添加更多schema关键字如additionalProperties，patternProperties，allOf，anyOf等、创建文件内部的schema引用以简化字段定义等。

3.3.8 自动生成应用框架代码

在上图中，用户点击向导审阅 API 规范页面右下方的下一步按钮即可为应用自动生成框架代码并在代码编辑器中浏览这些新生成的代码:

至此，用户已完成应用API规范向导的所有步骤，系统会将用户在以上步骤中输入的所有信息已被保存在系统数据库中。在结束代码浏览和编辑后，用户可以点击向导这一步右上方的“返回上一级”图标回到编辑设备页面，这时候，新创建的应用会出现在用户的编辑设备列表中，包括该应用的应用包名称、作者、版本号等信息：