如何利用 InterSystems 开放交换工具进行快速 API 开发

在本文中，我将分享我们在 2023 年全球峰会技术交流室中提出的主题。我和@Rochael.Ribeiro  

借此机会，我们就以下话题进行探讨：

• 用于快速 API 的开放交换工具
• 开放API规范
• 传统与快速 Api 开发
• 复合 API（互操作性）
• 规范优先或 API 优先方法
• API 治理和监控
• 演示（视频）

用于快速 API 的开放交换工具

当我们谈论快速现代 API 开发（Rest / json）时，我们将使用两个 Intersystems Open Exchange 工具：

第一个是用于快速开发 API 的框架，我们将在本文中详细介绍。

https://openexchange.intersystems.com/package/IRIS-apiPub

第二种是使用 Swagger 作为用户界面，用于 IRIS 平台上开发的 Rest API 的规范和文档，以及它们的使用/执行。其运行的基础是开放 API 规范 (OAS) 标准，如下所述：

https://openexchange.intersystems.com/package/iris-web-swagger-ui

 

什么是开放 API 规范 (OAS)？

它是全球范围内用于定义、记录和使用 API 的标准。在大多数情况下，API 甚至在实现之前就已经设计好了。我将在下一个主题中详细讨论它。

它很重要，因为它定义并记录了 Rest API 供其在提供者和消费者方面使用。但这种模式也有助于加快市场上工具（Rest API 客户端）的测试和 API 调用，例如 Swagger、Postman、Insomnia 等……

 

使用 IRIS 发布 API 的传统方式

想象一下，我们必须从现有的 IRIS 方法构建并发布 Rest API（如下图）。

以传统方式：

1：我们必须考虑消费者会如何称呼它。例如：将使用哪个路径和动词以及如何响应。无论是 JSON 对象还是纯文本。

2：在 %CSP.REST 类中构建一个新方法，该方法将处理调用它的 http 请求。

3：处理方法对最终用户预期的 http 响应的响应。

4：考虑一下我们将如何提供成功代码以及我们将如何处理异常。

5：为我们的新方法绘制路线。

6：向最终用户提供API文档。我们可能会手动构建 OAS 内容。

7：例如，如果我们有一个请求或响应有效负载（对象），则实施时间将会增加，因为它也必须记录在 OAS 中。

 

我们怎样才能更快？

只需使用 [WebMethod] 属性标记 IRIS 方法即可。无论是什么，该框架都会使用 OAS 3.x 标准来处理其发布。

为什么 OAS 3.x 标准如此重要？

因为它还详细记录了输入和输出有效负载的所有属性。

这样，市场上的任何 Rest Client 工具都可以立即耦合到 API，例如 Insomnia、Postman、Swagger 等，并提供示例内容以便轻松调用它们。

使用 Swagger，我们已经可以可视化我们的 API（上图）并调用它。这对于测试也非常有用。

API定制

但是如果我需要自定义 API 该怎么办？

例如：我希望路径是其他东西，而不是方法的名称。我希望输入参数位于路径中，而不是像查询参数那样。

我们在方法之上定义了一个特定的符号，我们可以在其中补充方法本身不提供的元信息。

 在此示例中，我们为 API 定义了另一条路径，并补充了信息，以便最终用户获得更友好的体验。

Rest API 的投影图

该框架支持多种类型的参数。

在此图中，我们可以突出显示复杂类型（对象）。它们将自动公开为 JSON 有效负载，并且每个属性都将为最终用户正确记录 (OAS)。

 

互操作性（复合 API）

通过支持复杂类型，您还可以公开互操作性服务。

这是构建复合 API 的有利场景，复合 API 使用多个外部组件（出站）的编排。

这意味着用作请求或响应的对象或消息将自动发布并由 swagger 等工具读取。

这是测试互操作性组件的绝佳方法，因为通常已经加载了有效负载模板，以便用户知道 API 使用哪些属性。

首先，开发人员可以专注于测试，然后通过定制来塑造 Api。

规范优先或 API 优先方法

当今广泛使用的另一个概念是在实现之前就定义 API。

有了这个框架，就可以导入 Open Api 规范。它自动创建方法结构（规范），只缺少它们的实现。

API 治理和监控

对于Api的治理，也建议一起使用IAM。

除了拥有多个插件之外，IAM 还可以通过 OAS 标准快速耦合到 API。

apiPub 为 API 提供额外的跟踪（参见演示视频）

演示

https://www.youtube.com/embed/IdJ1PqmhH3c
[这是一个嵌入式链接，但由于您拒绝了访问嵌入式内容所需的 Cookie，您无法直接在网站上进行查看。要查看嵌入式内容，您需要在 Cookie 设置中接受所有 Cookie。]

下载和文档

Intersystems 开放交换： https://openexchange.intersystems.com/?search=apiPub

完整文档：https: //github.com/devecchijr/apiPub

@Claudio Devecchi  致敬原创作者