第二章 使用 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

服务类，如下所示：

1. 以 JSON 格式创建或获取 REST 服务的 OpenAPI 2.0 描述。
2. 获取 REST 测试工具，例如 PostMan (https://www.getpostman.com/)。
3. 在测试工具中，创建如下 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 角色的成员，并且对给定的命名空间具有读/写访问权限。

1. 发送请求消息。

如果调用成功，

IRIS

在给定的包和命名空间中创建

disp

、

impl

和

spec

类。

1. 在测试工具中，检查响应消息。如果请求成功，响应消息将类似于以下示例：

{"msg":"New application myapp created"}

要完成基本的

REST

服务，请创建一个

Web

应用程序并定义实现。可以按任意顺序执行这些步骤。

创建 Web 应用程序

在此步骤中，将创建一个提供对

REST

服务的访问权限的

Web

应用程序。在管理门户中，完成以下步骤：

1. 单击System Administration > Security > Applications > Web Applications.
2. 单击创建新的 Web 应用程序。
3. 指定以下值：

• Name — Web 应用程序的名称；这在这个 IRIS 实例中必须是唯一的。最常见的名称基于运行 Web 应用程序的命名空间：/csp/namespace
• Namespace - 选择在其中生成类的命名空间。
• 启用应用程序Enable Application — 选中此复选框。
• 启用Enable — 选择 REST。
• 调度类Dispatch Class — 键入调度类的完全限定名称。这应该始终是 package.disp，其中 package 是包含生成的类的包的名称。

1. 单击保存。

使用 /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

服务。为此：

1. 使用 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 角色的成员，并且对给定的命名空间具有读/写访问权限。

1. 发送请求消息。

如果调用成功，

IRIS

将删除给定包和命名空间中的

disp

和

spec

类。

但是，

IRIS

不会删除

impl

类。

1. 在测试工具中，检查响应消息。如果请求成功，响应消息将类似于以下示例：

{
    "msg": "Application myapp deleted"
}

1. 手动删除实现类。

为安全起见，

/api/mgmnt

服务不会自动删除实现类，因为该类可能包含大量自定义。

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

a. 在管理门户中，单击

System Administration > Security > Applications > Web Applications

。
b. 在列出

Web

应用程序的行中单击删除。
c. 单击确定以确认删除。