第四章 使用 %REST.API 类创建 REST 服务

本章介绍如何使用 %REST.API 类来创建、更新和删除 REST 服务。

使用 %REST.API 类创建或更新 REST 服务

创建 REST 服务的推荐方法是从 REST 服务的 OpenAPI 2.0 规范开始，并使用它来生成 REST 服务类。要使用 %REST.API 类执行此操作：

1. 获取 REST 服务的 OpenAPI 2.0 规范，采用 JSON 格式，并将规范保存为文件。该文件必须是 UTF-8 编码的。
2. 在要定义 REST 服务的命名空间中，使用该文件创建 %DynamicObject 的实例。
3. 然后调用 %REST.API 类的 CreateApplication() 方法。此方法具有以下签名：

classmethod CreateApplication(applicationName As %String, 
                              swagger As %DynamicObject = "", 
                              ByRef features, 
                              Output newApplication As %Boolean, 
                              Output internalError As %Boolean) 
                              as %Status

• applicationName 是要在其中生成类的包的名称。
• swagger 是代表 OpenAPI 2.0 规范的 %DynamicObject 的实例。

还可以将此参数指定为规范的 URL、包含规范的文件的路径名或空字符串。

• features - 必须通过引用传递的 features 是一个多维数组，其中包含任何附加选项：
  • 如果 features("addPing") 是 1 并且如果 swagger 是一个空字符串，那么生成的类会包含一个用于测试目的的 ping() 方法。
  • 如果 features("strict") i 是 1（默认值），那么 会检查规范中的所有属性。如果 features("strict") i 为 0，则仅检查代码生成所需的属性。
• newApplication 作为输出返回，是一个布尔值，指示该方法是创建新应用程序 (true) 还是更新现有应用程序。
• internalError 作为输出返回，是一个布尔值，指示是否发生内部错误。

如果该方法生成一个新应用程序，IRIS 将在给定包中创建 disp、impl 和 spec 类。

如果该方法更新现有应用程序，IRIS 将重新生成给定包中的 disp 和 spec 类并更新 impl 类，保留对该类所做的编辑。

如果 OpenAPI 2.0 规范无效，则该方法不会进行任何更改。

4. 创建一个访问 REST 服务的 Web 应用程序，如本书前面的“创建 Web 应用程序”中所述。
5. 按照“修改实现类”一章中的描述定义实现。

下面显示了第一步的示例：

 set file="c:/2downloads/petstore.json"
 set obj = ##class(%DynamicAbstractObject).%FromJSON(file)
 do ##class(%REST.API).CreateApplication("petstore",.obj,,.new,.error)
 //examine error and decide how to proceed...
 ... 

使用 %REST.API 类删除 REST 服务

要使用 %REST.API 类删除 REST 服务：

1. 在可以找到 REST 服务的命名空间中，调用 %REST.API 类的 DeleteApplication() 方法。此方法具有以下签名：

classmethod DeleteApplication(applicationName As %String) as %Status

其中 applicationName 是包含 REST 服务类的包的名称。

2. （可选）手动删除实现类。

为安全起见，类方法不会自动删除实现类，因为该类可能包含大量定制。

3. 删除之前为此 REST 服务创建的 Web 应用程序（如果有）。为此：

a. 在管理门户中，单击System Administration > Security > Applications > Web Applications。

b. 在列出 Web 应用程序的行中单击删除。

c. 单击确定以确认删除。