MuleSoft 开源用于设计 RESTful APIs 的工具 RAML Tools

  • Abel Avram
  • 廖煜嵘

2013 年 11 月 9 日

话题:REST架构

近日,MuleSoft发布了 3 款基于 RAML的用于设计、评估和测试 RESTful APIs 的工具。

RAML来源于 RESTful API 建模语言,它是一种让人们易于阅读并且能让机器对特定的文档能解析的语言。RAML 是基于YAML,符合1.2 版本规范,能帮助设计 RESTful API 和鼓励对 API 的发掘和重用,依靠标准和最佳实践从而编写更高质量的 API。

这些由 MuleSoft 开发的基于 RAML 的 Web 工具分别是:

API Designer:一个专门用于创建和分享 API 标准的 web 编辑器。它能提示在什么地方应该使用什么元素以及指出创建的 RAML 文档中的错误。下面的代码片断中,有一个 books 的 API,其中有 get 方法,它返回同一个作者编写的所有书籍,而{booksId}部分有一个方法用于获得指定的书本并且 delete 方法用于从集合中删除书本。

从上面的代码片断可以看到,API 定义能充分利用用于定义更复杂资源的模式。同时,位于编辑器底部列出了方法、参数、资源和其他在 API 定义过程中需要的元素。

API Console:用于图形化显示和评估创建的 API,勾画出文档的结构和模型。下图显示了针对上面的例子所定义的 API 对应的控制台的样子,其中包括的 books 的 try 区域对于测试 API 调用特别有帮助:

API Notebook:一个用于测试 API 的 Javascript 控制台, 它本身是和其他的 API 一起组合而成。它能生成用 RAML 描述的 API 用户客户端并可以开始使用它们。

RAML 的开发是多人组成的工作团队,其中包括 MuleSoft 公司的 CTO Sarid、Intuit 公司的首席架构师 Ivan Lazarov、PayPal 的用户界面工程高级总监 Bill Scott、AngularJS 项目的发起人 Mi?ko Hevery、Programmable Web & API 项目发起人 John Musser、Box 公司的高级产品平台经理和在退伍军人事务部的总统创新研究项目(参考:http://en.wikipedia.org/wiki/Presidential_Innovation_Fellows)研究员 Kin Lane。针对该工作团队和他们的计划,Sarid 告诉 InfoQ:

RAML 目前还是处于早期阶段,我们要确保它的发展能有效地解决当今 API 设计和描述的迫切需要,并且没有陷入过于沉重的正式治理困境。为此,我们已经成立了一个志同道合的工作组,其成员都是来自在 API 方面有重大贡献的业界领先企业,这个工作组与来自社区的投入将带动 RAML 的发展。工作组的成员名单可以在raml.org 网站上找到。随着时间的推移,我们会调整成员,以保持组织的活跃,能让其受益于各种各样的观点同时也能精简以保持灵活,专注于目标。我们邀请社区人士参与这样一个开放的,关注长期战略目标及基于现实世界的讨论。

关于 RAML 的未来,Sarid 补充说道:

我们认为,RAML 已经解决了许多实际的 RESTful API 提供者和消费者当前所面临的问题,但绝不是所有。例如,我们还没有想通如何捕获如请求域中的输入参数和在响应 BODY 中输出数据之间的依赖 ―― 或者至少如何这样用一个整洁的、强大的和与 RAML 设计目标相一致的方式直观呈现。目前对于基于 JSON 的 API 我们也并不感到满意 ,因为刚仅是让 body 部分以 JSON schema 呈现;它们并没被更多的 XML schema 所采用,并且它们可能还不能满足 RAML 社区的其他一些要求。摆在我们面前并不清晰的是一个更大的问题,是 REST 设计上的限制,特别是超媒体。如果我们单单限制 RAML 在 RESTful API 方面,那么它则会 ,1 )不会应用到几乎任何现有的 API ,以及 2)目前对大多数 API 使用者并不可行。因此,我们从 REST 的 API 的基本部分着手 ―― 资源、方法、参数和不需要超媒体的 body -- 并将从那里演变。

RAML 目前的版本是 0.8,完整的规范定义通过https://github.com/raml-org/raml-spec下载。同时,以 CoffeeScript 编写的RAML parser已经发布。

查看英文原文:MuleSoft Open Sources RAML Tools for Designing RESTful APIs

REST架构