第十章 发现和记录 REST API

本章讨论如何发现实例上可用的 REST 服务以及如何为 REST 服务生成文档。

使用 /api/mgmnt 服务发现 REST 服务

/api/mgmnt 服务包括可用于发现 REST 服务类和启用 REST 的 Web 应用程序的调用。

发现 REST 服务

要使用 /api/mgmnt 服务来发现实例上可用的 REST 服务，请使用以下 REST 调用：

• 对于 HTTP 操作，选择或指定 GET。
• 对于 URL，请指定以下形式的 URL：

http://localhost:52773/api/mgmnt/v2/

或者，如果只想检查一个命名空间：

http://localhost:52773/api/mgmnt/v2/:namespace

其中 localhost 是服务器的名称，52773 是运行 IRIS 的 Web 服务器端口，命名空间是要检查的命名空间。

（请注意，这些调用会忽略手动编码的 REST 服务。要发现手动编码的 REST 应用程序，请使用调用 GET /api/mgmnt/ 和 GET /api/mgmnt/:v1/:namespace/restapps。）

如果调用成功，IRIS 以 JSON 格式返回一个列出 REST 服务的数组。例如：

[
  {
    "name": "%Api.Mgmnt.v2",
    "webApplications": "/api/mgmnt",
    "dispatchClass": "%Api.Mgmnt.v2.disp",
    "namespace": "%SYS",
    "swaggerSpec": "/api/mgmnt/v2/%25SYS/%Api.Mgmnt.v2"
  },
  {
    "name": "myapp",
    "webApplications": "/api/myapp",
    "dispatchClass": "myapp.disp",
    "namespace": "USER",
    "swaggerSpec": "/api/mgmnt/v2/USER/myapp"
  }
]

发现支持 REST 的 Web 应用程序

要使用 /api/mgmnt 服务来发现实例上可用的支持 REST 的 Web 应用程序，请使用以下 REST 调用：

• 对于 HTTP 操作，选择或指定 GET。
• 对于 URL，请指定以下形式的 URL：

http://localhost:52773/api/mgmnt

或者，如果只想检查一个命名空间：

http://localhost:52773/api/mgmnt/v1/:namespace/restapps

其中 localhost 是服务器的名称，52773 是运行 IRIS 的 Web 服务器端口，命名空间是要检查的命名空间。

使用 %REST.API 类发现 REST 服务

%REST.API 类提供可用于发现 REST 服务类和启用 REST 的 Web 应用程序的方法。

发现 REST 服务类

要使用 %REST.API 类来发现实例上可用的 REST 服务，请使用该类的以下方法：

• GetAllRESTApps()

GetAllRESTApps(Output appList As %ListOfObjects) as %Status

返回此服务器上的 REST 服务列表作为输出。输出参数 applist 是 %ListOfObjects 的实例，列表中的每一项都是 %REST.Application 的实例，其中包含有关 REST 服务的信息。这包括没有关联 Web 应用程序的任何 REST 服务。此方法忽略任何手动编码的 REST 服务。

• GetRESTApps()

GetRESTApps(namespace as %String,
            Output appList As %ListOfObjects) as %Status

以输出形式返回由命名空间指示的命名空间中的 REST 服务列表。

发现支持 REST 的 Web 应用程序

要使用 %REST.API 类来发现实例上可用的支持 REST 的 Web 应用程序，请使用该类的以下方法：

• GetAllWebRESTApps()

GetAllWebRESTApps(Output appList As %ListOfObjects) as %Status

返回此服务器上启用 REST 的 Web 应用程序的列表作为输出。输出参数 applist 是 %ListOfObjects 的实例，列表中的每个项目都是 %REST.Application 的实例，其中包含有关 Web 应用程序的信息。

• GetWebRESTApps()

GetWebRESTApps(namespace as %String,
               Output appList As %ListOfObjects) as %Status

作为输出，返回由命名空间指示的命名空间中支持 REST 的 Web 应用程序的列表。请参阅 GetAllWebRESTApps()。

为 REST 服务提供文档

记录任何 API 很有用，以便开发人员可以轻松使用 API。对于遵循 OpenAPI 2.0 规范的 REST API，可以使用 Swagger 开源框架根据规范的内容为您的 API 提供交互式文档。

一种选择是使用 Swagger UI 并提供文档的托管副本。对于演示：

1. 转到 https://swagger.io/tools/swagger-ui/
2. 单击 Live Demo
3. 在页面顶部的框中，以 JSON 格式输入 REST 服务的 OpenAPI 2.0 规范的 URL。

例如，在 IRIS 服务器上使用 GET /api/mgmnt/v2/:namespace/:application 调用。

4. 然后页面的下部显示文档，如以下示例所示：

image.png

在这里，可以查看有关每个呼叫的详细信息、测试呼叫并查看响应。

其他第三方工具使能够生成静态 HTML。 对此没有具体建议。