BT

如何利用碎片时间提升技术认知与能力? 点击获取答案

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

| 作者 Reza Shafii 关注 0 他的粉丝 ,译者 邵思华 关注 3 他的粉丝 发布于 2014年12月10日. 估计阅读时间: 12 分钟 | GMTC大前端的下一站,PWA、Web框架、Node等最新最热的大前端话题邀你一起共同探讨。

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 ShafiiMuleSoft公司的产品管理总监,MuleSoft是当今世界上使用最广泛的整合平台的供应商。

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

评价本文

专业度
风格

您好,朋友!

您需要 注册一个InfoQ账号 或者 才能进行评论。在您完成注册后还需要进行一些设置。

获得来自InfoQ的更多体验。

告诉我们您的想法

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我
社区评论

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

讨论

登陆InfoQ,与你最关心的话题互动。


找回密码....

Follow

关注你最喜爱的话题和作者

快速浏览网站内你所感兴趣话题的精选内容。

Like

内容自由定制

选择想要阅读的主题和喜爱的作者定制自己的新闻源。

Notifications

获取更新

设置通知机制以获取内容更新对您而言是否重要

BT