利用 IBM WebSphere Liberty 和 API Connect 释放 API 经济的价值链

Vijay Bhadriraju

高级软件工程师

Vijay Bhadriraju 是美国 IBM Software Group 北卡罗来纳州 Research Triangle Park 实验室 WAS SIP Technical Enablement 团队的一名高级软件工程师。他有 14 年的 IT 行业经验，其中 6 年从事开发 Rational 和 WebSphere Studio IDE 的工作，6 年从事 Smalltalk 咨询顾问服务。他目前从事使 IBM Business Partners 能够在 IBM IP Multimedia Subsystem 和 WebSphere 软件上操作的工作。他取得了计算机科学工程的学士学位。

当您可以访问强大的、可重用的 API 时，您就能够在当今的API 经济 中发起创新。要从 API 经济中受益，必须实现一条价值链，该价值链从创建 API 开始，以发现这些 API 并将它们集成到应用程序中结束。然而，创建、发布和管理 API 为参与这个过程的每个人（包括开发人员、管理员和企业利益相关者）都带来了一些挑战。其中一些挑战可能是如何使用 Java 轻松创建 API，或者如何让应用程序轻松找到这些 API，并了解如何使用它们。

IBM® WebSphere® Liberty 和 API Connect 可以帮助应对这些挑战，将企业资源转化为强大的、可重用的资产，为您的应用程序带来无以伦比的竞争优势。本文将向您介绍 API 经济价值链。本文基于我们如何实现 Java® API 并通过使用 WebSphere Liberty 发现它们的经验。我们展示我们如何将这些 API 导入到 IBM API Connect 中，并将它们发布到一个开发人员门户。通过遵循这一流程，您会有一个可以找到您的 API 的位置，学习如何使用它们，并简化将这些 API 集成到您的应用程序中的过程。

API 经济价值链

API 经济价值链始于将企业 IT 投资公开为 API，如下图所示。通过编目这些 API，您可以使用它们，例如，通过使用一个呈现 API 及其接口的自助服务门户。通过使用 API，您可以创建创新的应用程序，获得不同的体验。

使用 Java 创建 REST API

借助针对云的IBM Connect 产品，使用现有应用程序和数据来发现、创造和发布 API。IBM API Connect 是一个端到端 API 生命周期管理解决方案，它是让 IBM Connect 系列产品凝聚在一起的粘合剂，这些产品包括： IBM WebSphere Connect 、 IBM Business Operations Connect 、 IBM App Connect 、 IBM z/OS Connect 、IBM DB2 Connect 和IBM DataWorks。您可以将应用程序和数据公开为 API，并在它们与云之间建立连接。

解锁 API 经济价值链的第一步是使用 Java 创建 REST API。您可以使用 Java API for RESTful Web Services (JAX-RS) 标准，它支持创建遵循 REST 架构风格的 Web 服务。JAX-RS 标准使用了一些 Java 代码形式的标注，以定义 API 的功能和文档。

除了 JAX-RS 标准之外，您还可以使用 Swagger 。Swagger 是一个 Open API Initiative 规范和一个流行框架，可用来描述 API。它为开发人员和计算机提供了一个发现、了解和使用 API 的标准方式，无需访问源代码或文档。Swagger 规范包含一些以 Swagger 为核心的库，它们提供了一些 Swagger 注释，这些注释可与 JAX-RS 注释一起嵌入到 Java 代码中。JAX-RS 和 Swagger 注释的这种组合使得 API 描述和文档更具描述性且更容易使用。

IBM WebSphere Application Server Liberty 服务器是一个 轻量级的 、高度组合的、易于使用的、Java Enterprise Edition (EE) 7 认证的应用服务器。它是构建、运行和管理微服务的理想服务器。它以可组合特性的形式提供了各种功能，可以根据需要将这些特性动态地添加到服务器。这些功能之一是 jaxrs-2.0，它提供了必要的库来为 REST API 和 Swagger 开发带有注释的代码。支持此特性的 Liberty 服务器可以定义为 WebSphere Application Server Developer Tools (WDT) for Eclipse 中的测试服务器。WDT 是一个开发和测试 REST API 的理想工具，可免费获得。

下图显示了 Liberty 服务器的 server.xml 文件的服务器配置编辑器，该服务器是在支持 JAX-RS 特性的 WDT 中定义的。Liberty 服务器配置的所有细节都存储在 server.xml 文件中。这个配置文件就是您执行任何服务器配置更改需要编辑的唯一文件。

在启用测试 Liberty 服务器上的 JAX-RS 特性后，您可以将服务器定义为默认服务器运行时，以便在运行包含 JAX-RS API 的 Eclipse 项目时使用它。在 Server 窗口中，在 “Always use the following server when running this project（运行此项目时总是使用下面的服务器）” 下，选择 WebSphere Application Server Liberty at localhost 。

以下代码清单包含我们为了测试 jaxrs-2.0 特性而创建的 JAX-RS 和 Swagger 注释示例：

// Application Level Annotations @ApplicationPath("/cfb")  @SwaggerDefinition(tags={@Tag(name="CloudFirst Bank API", description="APIs for Account Transactions")})  public class CloudFirstBankApplication extends Application   // Class Level Annotations  @Path("/rest")  @Api("CloudFirst Bank API")  public class CloudFirstBankRestServices {}   // Method Level Annotations  @Path("/getAccounts/{id}")  @GET  @Produces("application/json")  public String getAccounts(@PathParam("id") String id) {  return MongoDBAccess.getAccounts(id); }

此代码示例包含以下注释：

• 应用程序级注释 。此级别包括一个 JAX-RS 注释和一个 Swagger 注释。JAX-RS @ApplicationPath 注释定义了根级别的 API 端点。当 API 端点显示在 Swagger 用户界面 (UI) 中时，@SwaggerDefinition 注释提供了该端点的名称和描述。
• 类级注释 。此级别包含两个 JAX-RS 注释。@Path 注释用于 API 端点的类级路径。此外，@API 注释是 Java 类中公开的 API 的定义。
• 方法级注释 。这个级别包含三个 JAX-RS 注释。@Path 注释是 API 端点的方法级路径。@GET 注释将方法注释为一个 HTTP GET 方法。此外，@Produces 注释对此方法的返回结果进行注释。

测试已发现的 API

在实现 API 并添加必要的注释后，需要测试这些 API。测试这些 API 的一个简单方法是使用 API Discovery (apiDiscovery-1.0) 特性，该特性是在 Liberty 中引入的。API Discovery 提供了发现所有 API 并将它们与 JAX-RS 和 Swagger 注释聚集在一起的功能。它还可以发现并聚集记录在 swagger.json 和 swagger.yaml 文件中的 API，它们已嵌入到应用程序中。

API Discovery 特性显示了通过使用开源 Swagger UI 发现的 API。在前面显示的 Liberty 测试服务器的 server.xml 文件中，启用了 apiDiscovery-1.0 特性。然后，我们展示了我们在启用了 jaxrs-2.0 和 apiDiscovery-1.0 特性的 Liberty 测试服务器上部署的应用程序。下图显示了已发现的 API，这样我们就可以测试它们，并确认它们的行为。右上框中显示了使用 Swagger 用户界面公开的 API。右下框中显示了已启用 JAX-RS 和 API Discovery 特性的 Liberty 测试服务器。

Liberty 中的 API Discovery 特性支持使用以下方法中的任何一个创建和发现 API：

• 自上而下的路径 。在该路径中，Swagger 定义是通过使用任何 Swagger 文档工具（比如 API Connect 或一个开源 Swagger 编辑器）记录的。已记录的 Swagger 文档文件 (swagger.json) 被嵌入到 Web 模块的 META-INF 文件夹中，API 代码是在不使用任何注释的情况下实现的。API Discovery 特性通过使用应用程序内的嵌入式 Swagger 文档中定义的 API 来创建运行时 Swagger 文档。在这种情况下，要在实现 API 之前设计它们。
• 自下而上的路径 。在该路径中，API 代码包含 JAX-RS 和 Swagger 注释。Liberty API Discovery 特性会根据注释为这些 API 生成 Swagger 文档。
• 混合路径 。在该路径中，一些 Java API 是通过注释公开的。其他 API 是通过 Web 模块的 META-INF /stub 文件夹内的一个 Swagger 文档文件公开的。通常，您会在现有的基于 servlet 的代码被公开为一个 API 时看到此路径，该 API 与通过 JAX-RS 标准公开的 API 混合在一起。在该路径中，API Discovery 特性可以利用应用程序内的 JAX-RS 注释和嵌入式的 Swagger 文档生成应用程序级 Swagger 文档。

编目和发布您的 API

在编写和测试 API 后，可以（向一个应用程序开发人员）传递 Swagger 注释，该注释描述了从应用程序调用 API 所需的位置和接口信息。但是，此过程可能仅能用于单个应用程序将会使用的有限数量的 API。您需要考虑当您有许多 API 时可能面临的问题，这些 API 来自需要使用它们的多个来源和多个应用程序。例如，您可以检查以下问题：

• 您如何了解哪些 API 可用？
• 您如何用一种简单、一致的方式了解 API 位置和接口？
• 您如何能在编码 之前 测试 API，以便可以了解 API 的行为方式？
• 您如何能与其他开发人员和 API 提供商分享学到的知识？

要解决这些问题，可以使用 IBM API Connect，它可以简化对 API D 编目、发布和管理。就我们而言，我们的目标是将 API 导入到 API Connect 中，并将它们发布到 API Connect Developer Portal，以便可以轻松地将它们集成到强大的互动参与系统中，比如移动应用程序。

快速上手，通过 IBM Bluemix® 实例化 API Connect。该方法可以节省时间本地安装时间。然后，将 API Connect 导入到通过 Liberty 中的 API Discovery 特性创建的 Swagger 文档中。

在 API Connect 的 Drafts 部分，通过导入 Swagger 添加一个 API。在 Import OpenAPI (Swagger) 对话框中，从某个 URL 导入 Swagger。在我们的示例中，我们输入了由 API Discovery 提供的 /ibm/api/docs URL。然后，单击 Import 。

API Connect 将 Swagger 定义拉取到 API Catalog 中。在我们的示例中，添加了我们所有的 CloudFirst Bank API。

在发布已导入的 API 之前，需要对相关的 Swagger 文件稍做更改。首先，在 Source 选项卡上，在 Host 下，将主机更改为 $(catalog.host) ，这样，在发布 API 时可以将它们解析到您的目录。

接下来，在 Assemble 选项卡上，添加带有一个代理策略的程序集，以便为 Liberty 服务器创建一个代理。在 Assemble 编辑器的 Proxy 属性对话框中，对于 Invoke URL，可以输入 Liberty 服务器的主机名（或 IP 地址）。

通过借助 API Connect 实现代理调用，您可以安全控制对 API 的访问，监控其使用情况，甚至限制调用这些 API 的次数。

测试已发布的 API

在发布 API 之前，需要在 API Connect 中测试它们。同时在 Assemble 选项卡上执行以下操作：

1. 单击 Test 图标。
2. 选择一个 API 进行测试。
3. 输入所需的输入参数，然后单击 Invoke 。
4. 查看结果，确保 API 如期工作。

如下图中所示，结果看起来是正确的。

现在，您已为发布做好准备。

将 API 发布到 Developer Portal

要将 API 从 Draft 区域发布到目录中，可以创建一个 Product（一个 API 集合），并向它添加一个 API 组。在 Product 内，单击 Publish 图标将 Product 发布到目录，在我们的示例中，该目录称为 Sandbox 。

现在，您已经将导入的 API 从 Draft（或 work）区域发布到 API 目录。

通常，管理员会将 API 发布到 Developer Portal。对于这个项目，我们就是管理员。作为管理员，可以转到 Catalog，并找到处于 Staged 状态的 API。然后，单击 Publish 将它发布到 Developer Portal。

在 API Connect Developer Portal 中，您可以查看所有可用的 API，包括您在 Liberty 中创建的、导入 API Connect 的和最后公布的一组 API。通过选择您的 API 集合，您可以看到每个 API 及其接口。您还可以测试 API，并抓取一个代码片段，您可以用该代码片段使用多种语言来调用 API，这些语言包括 Java，Node.js、PHP 和 Swift。

结束语

使用了您的企业资源的 API 可以丰富您的应用程序，帮助提供新的、创新的解决方案来应对您的业务挑战。为了实现这些 API 的价值，您必须成功实现 API 经济价值链。您可以通过创建您的 API 开始您的价值链，在用 Java 实现 API 时使用 JAX-RS 标准，然后，通过使用 WebSphere Liberty API Discovery 特性发现它们。在您发现 API 之后，可以将它们导入到 IBM API Connect 中，这样，您就可以将它们发布到一个开发人员门户，向应用程序开发人员呈现您提供的所有 API。借助 API Connect Developer Portal，您可以轻松找到可用的 API，了解它们的接口和行为，并获得代码片段，使得将这些 API 集成到其应用程序中变得更容易。

相关主题： IBM API Connect 产品文档

相关主题： IBM API Connect Developer Center

相关主题： WASdev Developer Center

相关主题： Java 和 Liberty 快速入门指导