第二章 使用 api mgmnt 服务
第二章 使用 /api/mgmnt/ 服务
本章介绍如何使用 /api/mgmnt 服务来创建、更新和删除 REST 服务。
/api/mgmnt 服务还提供了可用于发现和记录 Web 服务的选项，如本书后面所述。
使用 /api/mgmnt 服务创建 REST 服务
创建 REST 服务的推荐方法是为 REST 服务创建 OpenAPI 2.0（也称为 Swagger）描述，并使用它来生成 REST 服务类。如果您正在实现由第三方定义的 REST 服务，他们可能会提供此 OpenAPI 2.0 描述。有关 OpenAPI 2.0 描述格式的详细信息，请参阅 OpenAPI 2.0 规范。以下主题描述了如何使用 /api/mgmnt 服务来执行此操作。
使用 /api/mgmnt 服务生成类
第一步，生成 REST 服务类，如下所示：
- 以
JSON格式创建或获取REST服务的OpenAPI 2.0描述。 - 获取
REST测试工具，例如PostMan(https://www.getpostman.com/)。 - 在测试工具中，创建如下
HTTP请求消息：
- 对于
HTTP操作，选择或指定POST。 - 对于
URL，请指定以下形式的URL：
http://localhost:52773/api/mgmnt/v2/namespace/myapp
其中 localhost 是服务器的名称，52773 是运行 IRIS 的 Web 服务器端口，namespace 是要在其中创建 REST 服务的名称空间，myapp 是要在其中创建类的包的名称.
- 对于请求正文，以
JSON格式粘贴Web服务的OpenAPI 2.0描述。 - 将请求正文类型指定为
JSON(application/json) - 为
IRISUsername和IRISPassword参数提供值。对于IRISUsername，指定一个用户，该用户是%Developer角色的成员，并且对给定的命名空间具有读/写访问权限。
- 发送请求消息。
如果调用成功， IRIS 在给定的包和命名空间中创建 disp、impl 和 spec 类。
- 在测试工具中，检查响应消息。如果请求成功，响应消息将类似于以下示例：
{
"msg": "New application myapp created"
}
要完成基本的 REST 服务，请创建一个 Web 应用程序并定义实现。可以按任意顺序执行这些步骤。
创建 Web 应用程序
在此步骤中，将创建一个提供对 REST 服务的访问权限的 Web 应用程序。在管理门户中，完成以下步骤：
- 单击
System Administration > Security > Applications > Web Applications. - 单击创建新的
Web应用程序。 - 指定以下值：
Name—Web应用程序的名称；这在这个IRIS实例中必须是唯一的。最常见的名称基于运行Web应用程序的命名空间：/csp/namespaceNamespace- 选择在其中生成类的命名空间。- 启用应用程序
Enable Application— 选中此复选框。 - 启用
Enable— 选择REST。 - 调度类
Dispatch Class— 键入调度类的完全限定名称。这应该始终是package.disp，其中package是包含生成的类的包的名称。
- 单击保存。
使用 /api/mgmnt 服务更新 REST 服务
API 管理工具使能够更新生成的类，而无需更改在实现类中所做的编辑。如有必要，将重新生成该类，但保留编辑。
要更新 REST 服务，请使用“使用 /api/mgmnt 服务生成类”中列出的步骤。
如果更新成功，IRIS 会重新生成给定包中的 disp 和 spec 类并更新 impl 类，保留对该类所做的编辑。响应消息将类似于以下示例：
{
"msg": "Application myapp updated"
}
如何更新实现类
如果之前编辑过 impl 类， 会保留这些编辑，如下所示：
- 所有方法的实现都保持原样。
- 添加的任何新类成员都将保持原样。
但是，会重新生成类和每个生成方法的描述（/// 注释）。如果任何实现方法的签名发生更改（例如，因为规范已更改），会更新签名并将以下注释添加到该类方法：
/// WARNING: This method's signature has changed.
使用 /api/mgmnt 服务删除 REST 服务
API 管理工具还使能够轻松删除 REST 服务。为此：
- 使用
REST测试工具，创建HTTP请求消息，如下所示：
- 对于
HTTP操作，选择或指定DELETE。 - 对于
URL，请指定以下形式的URL：
http://localhost:52773/api/mgmnt/v2/namespace/myapp
其中 localhost 是服务器的名称，52773 是运行 IRIS 的 Web 服务器端口，namespace 是要创建 REST 服务的名称空间，myapp 是包含 REST 服务类的包的名称。
- 为
IRISUsername和IRISPassword参数提供值。对于IRISUsername，指定一个用户，该用户是%Developer角色的成员，并且对给定的命名空间具有读/写访问权限。
- 发送请求消息。
如果调用成功，IRIS 将删除给定包和命名空间中的 disp 和 spec 类。
但是， IRIS 不会删除 impl 类。
- 在测试工具中，检查响应消息。如果请求成功，响应消息将类似于以下示例：
{
"msg": "Application myapp deleted"
}
- 手动删除实现类。
为安全起见，/api/mgmnt 服务不会自动删除实现类，因为该类可能包含大量自定义。
- 删除前为此
REST服务创建的Web应用程序（如果有）。为此：
a. 在管理门户中，单击System Administration > Security > Applications > Web Applications。
b. 在列出 Web 应用程序的行中单击删除。
c. 单击确定以确认删除。