使用 RAML 与 APIkit 以实现 API 需求层次中所定义的目标

API 的流行使商业方式出现了快速的改变，各种令人兴奋的创新之举层出不穷，并且围绕着传统的企业级商业模型，涌现出了多种新型的开发者生态系统。API 已经实现了 SOA 愿景中所承诺的景象，即通过简单的接口，在受控的情况下访问数据与业务逻辑。

API 使得底层的应用程序不必受限于预定义的用户界面的功能，这些应用程序的功能可以通过 API 方式为其它应用程序所用，以实现更多更好的服务，而且这种灵活性几乎是没有限制的。

ProgrammableWeb.com 上收集了超过 1 万个公共 API，并且这个数字还在快速增长，看到这一点，我们也应该对 API 在当今世界上的重要性心存敬意。让我们来看看几个 API 应用的例子，以了解各个公司是如何通过 API 来驱动它们的创新的。

Amazon 为用户打造自己的技术平台提供了一个坚实的基础，它不仅为每项功能提供了一个 web 控制台管理器，并且提供了一套完整的 API。这使得 Amazon 的服务能够非常方便地重新包装并整合到客户的解决方案中。与之类似的是，Salesforce 平台上的多数用户操作并非来自 web 用户界面，而是通过使用它们的 API 产生的。Salesforce 允许通过 API 方式方便地访问底层的 CRM 数据，因此该平台的功能能够很容易地整合到客户自己的企业解决方案中。

Amazon 和 Salesforce 的 API 虽然是个有趣的例子，但它的应用只占据了当今所有企业级 API 的冰山一角。当今的企业所采用的 API，大部分是为同一间公司中的一部分内部用户所使用，或者是为某几个固定的合作伙伴所使用。

在公司 API 的设计与构建上，RESTful 方式代表了主流的趋势，在使用度上已经抛离了 SOAP web services 的使用方式，从以下这张由 ProgrammableWeb.com 的 API 目录所创建出的图形就可以得出这一结论。这一趋势也同样延展到了为内部用户及合作伙伴所使用的企业 API。

图 1 – 基于 REST与 SOAP方式构建的 API数量比较（来源： programmableweb.com）

虽然这一趋势表现得异常猛烈，但业务目前还没有出现一套完善的解决方案，能够满足 RESTful API 的产品干系人所需的所有需求。实际上，如果有人能够模仿著名的马斯洛需求层次结构理论来规划出一套API 需求层次结构，那他将会得到一个类似于下图的金字塔图形。

换句话说，你必须确保你的API 能够实现这一层次理论的预定目标。如此一来，你就需要以一种高效且可维护的方式实现你的API。当实现完成后，你还需要设法吸引用户的目光，让他们真正开始使用这套API。而在完成了以上工作后，你还需要对这些已经产生价值的API 进行管理与维护。在使用马斯洛需求层次结构的时候，人们会倾向于走捷径的方式，越过底层直奔金字塔顶。这种时候要想想母亲的叮嘱：这不健康！在本文接下来的部分中，我们将采用一种更健康的方式，并且关注于企业级API 设计与实现这两个最基本的需求，同时为你展示如何使用RESTful API 建模语言（RAML）及相关工具，并配合APIkit 的使用，实现这两个基本需求。

使用RAML 进行API 设计

一套RESTful API 的设计总是围绕着这些内容：资源名称、结构、相关的方法、参数、请求与响应的内容体（以实体的方式进行展现），以及响应码。这些设计为开发者创建应用程序定义好了契约。优秀的API 设计应该能够让应用程序的开发者很容易理解这套API 的目的与使用方式，因此很快就能够上手使用。API 的设计也应该为所针对的应用程序类型进行优化，比方说，一个移动应用与一个Web 应用在API 的使用上有不同的限制，移动应用对于API 方法调用的数量和返回的响应数据的大小会更加敏感许多。

为了达到这种良好的API 设计，API 的开发者需要迭代式地以表达式的风格定义API 的结构，并且与预计使用这套API 的应用程序开发者共同进行评审，以此评估这套API 的可用性，以及它是否适合于他们打算创建的应用程序。来看一下RESTful API 建模语言（RAML）， RAML.org 对它的描述是：“RAML 是一种能够以简单与简洁的方式描述 RESTful API 的语言。它鼓励重用，允许 API 探索及模式共享。”

RAML 的优势不仅在于它能够允许开发者表达他们的 API 设计，它还有一个重要优势在于：虽然它出现的时间并不长，但已经多个基于它的开源项目存在，这些项目能够促进良好的 API 设计。API Designer 是其中最重要的一个项目，它为使用 RAML 进行 API 结构设计提供了一个编辑器，并且能够在一个互动控制台中实时显示出 API 的更新，以实现用户与 API 之间的交互。

图 2 – API Designer**** 的截图

通过结合使用 RAML 与 API Designer，API 的开发者就可以采取一种 API 优先的设计方式。他们首先会在 API Designer 的编辑器中以 RAML 语言绘制出一套 API 的初步设计，同时将该设计分享给有可能会针对这套 API 进行应用程序开发的开发者们，可以选择只分享 RAML 文档本身，也可以选择将 RAML 自动生成的互动控制台分享给对方。实际上， API Designer 本身就整合了一套用于模拟（mock）的服务，只需提供相应的 RAML 规格说明，该服务就能够自动生成一套关于该 API 的实现。模拟服务能够在互动控制台中进行访问，也可以在类似于 API Notebook 这样的 RAML 工具中访问，甚至可以让在不同设计周期的移动应用进行访问，这也意味着应用的设计可以与 API 的设计同时进行了。它的好处在于能够通过周期性地反馈循环，在开始具体实现之前，就能够为预计的用户提供一套清晰易用于 API。

当 API 的设计结束后，就可以根据 API 开发者的偏好及需求，决定以何种语言及框架具体实现。越来越多的开源项目都提供了根据 RAML 的定义简化 API 具体实现的功能。这些项目包括有：一个为 RAML 生成 JAX-RS 桩（stub）的工具，以及由 MuleSoft 实现的开源项目 APIkit，它能够通过使用 Mule flow 生成一套由 RAML 定义的 API。接下来让我们仔细观察一下 APIkit，看一下它是如何帮助开发者们实现 API 需求结构中的第二个条目——“API 实现”的。

使用 APIkit 实现 API

一套 API 的实现不仅包括了一系列的新业务逻辑，也包括连接与整合的逻辑。很多情况下，连接与整合的逻辑并不简单，需要复杂的自定义代码进行实现。在这种情况下，使用 Mule flows 进行 API 的实现的方式就比使用自定义代码的实现有更大的好处，因为 Mule flows 允许 API 开发者充分利用 MuleSoft Anypoint 平台的能力来交付 API。

这一平台的能力包括有：高级消息处理（比方说将某个消息的片段进行切分，或是整合）、复杂的数据转换，并且能够通过简单而健壮的连接性，连接到多达数百种 SaaS 应用或是本地应用程序的终结点上，这些应用包括 Salesforce、SAP 或是 Microsoft Dynamics，并且支持多种异质的连接协议，例如 FTP/S、MQ（消息队列）、JMS（Java 消息服务）或 AMQP（高级消息队列协议）。

APIkit 是一个开源项目，它极大的简化了在 Mule flows 上开发由 RAML 语言定义的 API 的难度。这个项目中还包括了基于 Maven 和基于 Eclipse 的工具，可直接用于 MuleSoft 的 Anypoint Studio IDE 工具中。对于初学者来说，可以基于一个现有的 RAML API 定义创建一个全新的 Mule 项目，并自动生成一个整合 flow，并将该整合 flow 与由 RAML 规格中定义的每一组资源 / 方法对进行关联。

图 3 – 在 Anypoint Studio**** 中使用 APIkit Project

由 APIkit 生成的 Mule flow 包含了一个默认的实现，它能够返回在 RAML API 中定义的响应的一个示例，这使得该项目能够作为这套 API 的一个模拟实现被使用。这样，开发者就得到了一套完整的 API 实现，它包含了可以运行的模拟版本的逻辑。开发者随后以迭代式的方式，通过使用 Mule 中的各种构件，实现每一组资源 / 方法对的真实的整合逻辑。

开发者还能够完全利用 Anypoint Studio 所包含的各种功能，例如 Visual Flow 调试器，或者在实现高级数据转换时也可以用到 Anypoint DataMapper 。APIkit 还允许将传入的 API 请求路由至现有的 Mule flow 中（而不用完全重新创建新的 flow），它还能够方便地将 Java 及 Mule 中的异常映射至 API 必需返回的 HTTP 响应代码。

最后，APIkit 项目中也包含了一个预定义的交互控制台，这和 API Designer 工具中所包含的（也是动态生成的）控制台是完全相同的。该控制台允许 API 与应用程序的开发者方便地与 API 进行交互，包括浏览它的 RAML 嵌入文档。

当 API 开发者完成了 API 的实现之后，就可以将它部署到 MuleSoft Anypoint 平台上了，可以选择在一个本地的 Mule ESB 实例上托管该平台，也可以选择通过 MuleSoft iPaaS 服务，将 API 托管在 CloudHub 这一云端环境中。

结论

通过这篇文章，我们介绍了 REST API 建模语言（RAML）以及基于它的一些开源项目，包括 API Designer 和 APIkit，并展示了如何使用 RAML 以满足 API 需求结构中的两个最基本的需求，即 API 设计与 API 实现。

关于作者

Reza Shafii是 MuleSoft 公司的产品管理总监，MuleSoft 是当今世界上使用最广泛的整合平台的供应商。

查看英文原文： Article: Minding the API Hierarchy of Needs with RAML and APIkit