使用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