转载

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

 

当您可以访问强大的、可重用的 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,您可以创建创新的应用程序,获得不同的体验。

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

点击查看大图

使用 Java 创建 REST API

 

借助针对云的 IBM Connect 产品,使用现有应用程序和数据来发现、创造和发布 API。IBM API Connect 是一个端到端 API 生命周期管理解决方案,它是让 IBM Connect 系列产品凝聚在一起的粘合剂,这些产品包括:IBM WebSphere ConnectIBM Business Operations ConnectIBM App ConnectIBM z/OS ConnectIBM DB2 ConnectIBM 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 文件中。这个配置文件就是您执行任何服务器配置更改需要编辑的唯一文件。

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

点击查看大图

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

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

以下代码清单包含我们为了测试 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 测试服务器。

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

点击查看大图

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

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

点击查看大图

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

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

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

点击查看大图

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

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

点击查看大图

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

测试已发布的 API

 

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

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

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

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

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

将 API 发布到 Developer Portal

 

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

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

点击查看大图

现在,您已经将导入的 API 从 Draft(或 work)区域发布到 API 目录。

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

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

点击查看大图

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

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

点击查看大图

结束语

 

使用了您的企业资源的 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 快速入门指导


    
正文到此结束
Loading...