为 Web__ 设计、实现和维护 API__ 不仅仅是一项挑战;对很多公司来说,这是一项势在必行的任务。本系列 将带领读者走过一段旅程,从为API__ 确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在Web__ 上维护公共API _。沿途将会有对有影响力的人物的访谈,甚至还有 API__ 及相关主题的推荐阅读清单。_
这篇 InfoQ__ 文章是 Web API从开始到结束系列文章中的一篇。你可以在这里进行订阅,以便能在有新文章发布时收到通知
Mike Kelly 是一位软件企业家,也是 Stateless 的创建人,Stateless 是一家为各个企业提供 API 顾问服务,帮助他们制订策略、进行设计,并且应对实现方面的挑战的公司,Kelly 目前与他的妻子和三个孩子定居在 London 郊外的温彻斯特小城。从年轻时起,Kelly 就活跃在 web 这一领域中,他在 API 与 REST 社区中也是众所周知的活跃人士。
2011 年,他发布了超文本应用语言( HAL )这种用于 API 的媒体类型。从那时起,HAL 就成为了 API 超媒体格式方面最耀眼的明星,而 Mike Kelly 也被公众视为在 Web API 方面的一位领导专家。他并不经常参与各种公众活动,但最近却破例参加了在密歇根州的底特律举办的 2014 API-Craft 大会,并且在会议上举办了一次演讲,谈论了 HAL 的现状以及超媒体和 API 在未来的应用。
在那次会议后不久,我们有幸对 Mike 进行了一次访问,谈到了他创建 HAL 背后的原因,以及他在这三年来与 web 开发者和 API 社区交流的经验。
InfoQ**:在 2011年七月,超文本应用语言(HAL)媒体类型在 IANA 获得了注册。请问你创建 HAL背后的动机是什么呢?**
Mike:当时我正在帮助一位客户设计他们的 Saas 产品,按照该产品的路线图设计,它们将会面临大量后端的变更,并且将影响到整个 API 的 URL 结构。我希望所设计出的 API 能够在应对这些变更时尽量不要受到影响,而超媒体看起来对于该产品是种理想的设计风格。
InfoQ:这么说来,其中的一个关键目标就是尽量减小“时间的推移”所带来的影响吗?
Mike:不错。另外还有一个设计目标,就是尽量提升开发者上手使用这套系统的体验,因为 API 集成是这个产品的关键价值所在,也是销量的关键驱动力之一。对我来说,这意味着我们需要一套清晰的、容易获取的说明文档,并且 API 本身一定要易于使用。
出于以上原因,我决定创建一个 API 浏览器,让开发者可以随时参考并且探索这套 API 的应用及相关的文档,这与他们对某个 web 应用的探索方式差不多。因此,我需要一种通用的格式,在整套 API 中使用这一格式,随后就可以针对这种格式创建出 API 浏览器。
InfoQ**:所以说 HAL最初的目标就是为了解决你的某个项目中所遇到的问题。用 Eric Raymond的话来说,你只是为自己“挠了挠痒”。既然 HAL只是用来处理你这个 SaaS产品的问题,那它又怎么会成为一种通用的格式,并且为这么多人所接受呢?**
Mike:HAL 在那个项目中确实起到了作用,因此我将这一想法分享给了 API 界的同行们,让他们看看我为这个基于 JSON 的通用格式编写的一些示例。人们的反馈相当正面积极,甚至有一部分人已经打算在他们自己的 API 中使用这个还没有定稿的格式了。我因此燃起了动力,总之,我最后创建了一个网页,对这个设想进行更为详细的描述(我在此将这一设想称之为超媒体应用语言,或 HAL),最终成为了一个正式的互联网标准草稿。
InfoQ**:在最近几年来,不断有新的以 API为中心的媒体类型被注册,而 HAL是这一浪潮的带头者。你觉得这一浪潮的起因是什么?为什么新的设计不断涌现?**
Mike:我想这是因为人们逐渐认识到,虽然说每种 API 所对应的商业领域可能是完全不同的,但从架构风格的角度来看,有许多内容是相通的。我们可以从超媒体开始,将这些相通的内容映射到 API 的设计中,这就使我们能够开发及分享这些工具及技术,让它们去应对更广泛的问题。
InfoQ**:说到“相通的内容”,HAL的设计中很重要的一点,就是它专注于消息中的“链接与资源”,并且依赖于可读的文档,对如何使用 HTTP方法对这些资源进行操作加以解释。为什么你会使用这种方式设计 HAL**呢?
Mike:我发现对于我所用过的大多数 API 来说,它们都需要提升开发者上手使用的体验,因为它驱动了关键的成功指标,例如 API 使用者的接受度与活跃度。在我看来,要实现这一点,你必须让 API 消息保持简洁,并且用详实的、可读的文档为开发者说明这些消息的具体细节。
InfoQ:因此你的设计依赖于一种机器可读的格式,以及一种人类可读的文档。如果让消息体包含执行一个方法所需的所有细节,例如参数、方法名称等等,又会产生怎样的结果?
Mike:我认为为媒体类型添加新的特性会产生一种收益递减效果——越多不代表越好,越多的特性代表使用该种格式的客户的负担更重。HAL 是我认为在超媒体设计中最平衡有效的结果。
InfoQ**:在 2014年早期,Amazon**宣称会在它们的 AppStream API中使用 HAL,你是否也为 Amazon进行了某些指导,帮助它们学习如何在 API中使用 HAL。
Mike:令我感到高兴的是,我没有直接参与此事。我想这是个积极的信号,说明 HAL 的设计与规格正在朝着正确的方向前行。使用 HAL 进行设计的 API 越来越多,已经多到难以计数了!
InfoQ**:因此 API社区自己选择了对 HAL的使用,以及帮助处理 HAL方面的相关问题。我知道你维护着一个 HAL相关的邮件列表( HAL Discuss ),这个列表也十分活跃。我注意到有许多人提出 HAL相关的问题,或是分享在 HAL**方面的经验,但你本人的发帖数似乎并不多,为什么呢?
Mike:由于 HAL 使用者社区能够积极地分享他们的经验,以及对规格的理解,因此我不再需要回答这个邮件列表中所产生的大量问题,或是给出许多建议了,这也说明了 HAL 正在快速发展。我觉得这是一件很好的事,因为 HAL 在目前的发展已经超出我了所构思的设计目标。幸运的是,我对 HAL 的解读及社区对它的理解和使用看起来是高度一致的。
InfoQ**:我手头上并没有一张图表,但我听说在近年来各种新型 API设计中,HAL是使用率最高的超媒体格式,是真的吗?你觉得产生这一结果的原因是什么?为什么 HAL**能够吸引这么多开发者使用?
Mike:我也一样没有任何图表,但我同意 HAL 看起来确实是使用率最高的。我认为原因在于 HAL 的设计非常平衡,它引入了超媒体,但又不会过度影响 JSON 格式的简易性。实际上,我想以上这一点只是原因之一,另一个重要的原因,或许只是 HAL 在正确的时间出现在正确的地方罢了。
InfoQ**:好的,我们又回到之前所讨论过的一些设计上的决策了。比方如,在 HAL Discuss邮件列表中经常谈论起的某个主题,是有人认为 HAL缺乏了在 HTML**、Siren**、Collection+JSON等格式中常见的内联“形式”。有些人希望在 HAL规格中加入这一特性,你对此有什么要说的吗?**
Mike:虽然你可以尝试为 HAL 加入更多动态元素,但我坚持反对这么做,因为新增加的复杂性会使得消息体的简洁性降低,从而影响到开发者上手使用的体验。而且也无法处理现实世界中的问题。
之所以有许多人希望在 API 消息体中加入“形式”,是因为他们需要在 GUI 应用中使用这一信息。但我的想法是,HTML 本身已经是一个完美的表现 GUI 形式的超媒体格式了,它具有高度一致性,并且开发者们也非常熟悉 HTML。对于那些在 JSON 中引入了形式的媒体类型来说,我感觉它们是在重复发明那个复杂的轮子,有事倍功半之嫌。
InfoQ**:因此你还是将 HAL视为一种机器与机器(M2M)之间通信的使用方式,而且你认为将这一信息内联对机器来说没有很大的用处,是吗?**
Mike:真要说起我对 M2M 中形式的使用方面的想法,我想这得专门再进行一次访谈才行!总的来说,我对此保持怀疑,而且我也没有看到有任何有力的示例(无论是理论的还是现实世界中的)能够说服我:为这一功能增加 HAL 的复杂性确实是值得的。
说起这一点,前一阵子我为 HAL 设计了一个扩展,称为 HALO,其中就加入了这种动态方面的功能。人们对它很感兴趣,但老实说,我对于它的实用性并不太看好,也没有什么动力继续推动这个项目的开发。
InfoQ**:在一年多之前,你创建了一个 HAL RFC **文档,其中的内容如今已经过期了。你是否计划重新修改这份文档呢?
Mike:是的,我最近刚刚在 HAL Discuss 邮件列表中发送了一个请求,看看大家对于这个规格说明有没有什么最后的反馈与调整意见。如果哪位读者有任何意见希望进行分享,请提交一个 pull 请求!
InfoQ:从你最初发布 HAL以来已经过去了三年。如果能从头再来一次,你会做出什么不同的选择吗?有哪些东西是你希望能够早点知道的呢?
Mike:我对 HAL 目前的结果以及它一路前行的过程都感觉十分满意。
或许我应该更快地编写出 HAL 浏览器并更早地发布它,因为它确实“触动”了许多人的心灵。此外,我也觉得自己应该更积极地参与一些引人关注的开源 web 框架的早期开发过程,例如 rails-api 和 ember.js,因为这些框架可以使用 HAL 这样的通用媒体类型作为它们的默认消息格式,这样一来就会使得 HAL 的应用更加广泛了。需要指出的是,rails 与 ember 项目都出现了第三方的 HAL 类库,并且许多其它语言及框架也有第三方的 HAL 类库存在。
InfoQ:好的,最后一个问题了:如今每隔几个月就有一种新的格式会出现。作为这股媒体类型设计者浪潮的带头人之一,你对于那些正在考虑创建新的媒体类型的同行有什么建议吗?
Mike:我的建议就是不要想着加入太多的特性。你的规格越简短越好。让它解决你的实际问题,不要去自找麻烦。不要自作聪明,尽量使用直白的语言和简短的示例。尽早将你的设计分享给大家,让设计越来越清晰明确。最后一点,不要尝试在 JSON 中重新发明 HTML!
关于受访者
Mike Kelly是一位软件企业家,也是 Stateless 的创建人,Stateless 是一家为各个企业提供 API 顾问服务,帮助他们制订策略、进行设计,并且应对实现方面的挑战的公司,Kelly 目前与他的妻子和三个孩子定居在 London 郊外的温彻斯特小城。他主要为伦敦及欧洲的客户提供服务。最近,他来到了密歇根州的底特律,作为一位特邀嘉宾及讲师参加了 API Craft 大会。他在演讲中介绍了超媒体 API,以及由他设计的那套非常流行的超媒体设计,名为超文本应用语言(HAL)。
为 Web__ 设计、实现和维护 API__ 不仅仅是一项挑战;对很多公司来说,这是一项势在必行的任务。本系列 将带领读者走过一段旅程,从为API__ 确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在Web__ 上维护公共API _。沿途将会有对有影响力的人物的访谈,甚至还有 API__ 及相关主题的推荐阅读清单。_
这篇 InfoQ__ 文章是 Web API从开始到结束系列文章中的一篇。你可以在这里进行订阅,以便能在有新文章发布时收到通知
评论