API 设计中人的因素:专访 Apiary 的 Jakub Nesetril

  • Saul Caganoff
  • 张卫滨

2013 年 11 月 28 日

话题:测试语言 & 开发架构

API 的设计与描述并不仅仅是机器之间的技术接口。API 设计和描述并不仅仅是机器间的技术接口。  Apiary的联合创始人兼 CEO Jakub Nesetril 指出 API 描述的真正使用者是开发人员,需要考虑到开发人员的参与、可用性以及交流等方面。最近,就 API 设计以及 API 工具和工作流,我们与 Apiary 进行了交流。

InfoQ: Jakub,你最近在 API Strategy 会议做了关于API 设计最佳实践的演讲。你提到了“构建 API 并没有绝对正确的方式”。能谈一下你的这一理念吗,它是如何影响 Apiary 正在做的事情的?

JN::长期以来,API 被视为两个电脑程序之间的接口。实际上,API 是开发人员之间的接口——也就是真实的人之间。如果开发人员不了解怎样使用 API,那么一切都完蛋了——你的项目肯定会失败。

API(以及更通用意义上的软件接口)非常类似于 UI 设计:它受到时尚周期的影响,并且不同的文化背景会有差异(在编程中,指的就是语言和框架的文化),对此很容易形成成见,但是针对什么是正确的设计,没有人能达成共识。

探寻“唯一正确的”UI 设计是很愚蠢的做法,与此类似,API 设计中也没有唯一的金科玉律。但是,有一些技术可以改变既有的主观性。在 UI 界面的演化中,我们看到近十年来,出现的趋势是关注以用户为中心的设计和用户体验。我们需要将这种方式拿到 API 开发之中,与客户和利益相关方实现敏捷、快速集成以及紧密的反馈环路。

InfoQ: 现在有很多的 API 描述标准可供采用,包括你自己的API Blueprint。有一些是基于 JSON、Markdown、YAML 或 XML 的。你认为哪种方式最好呢?相对其他可选方案,是什么促使你选择了 Markdown 呢?

JN: 当 Apiary 成立的时候,XML、JSON 以及 YAML 格式就已经存在了,我们曾经努力尝试不引入新的格式。但我们强烈感觉到这些语言太复杂了,尤其是考虑到其他角色——如技术文档编写人员或 API 的使用者——要参与进来的时候。当它们要携带大量人类可读的文本内容时会相当繁琐,但是好的 API 文档一般都会包含这样的信息。

我们寻找一种在开发人员内部比较流行的格式,它能够用来编写结构化的数据,同时又能书写成段的文字。我们想找一种人类很易于读写的形式。希望它能够很容易被技术人员和非技术人员所理解。多年以来,markdown 几乎被所有的开源项目所使用,同时也是 GitHub Pages 和 Jekyll 出版系统的核心。开发人员已经使用它很多年了。

InfoQ: 有些开发人员倡议将超媒体(hypermedia)作为契约式 API 开发的可选方案。这个问题似乎已经有很显然的答案了,但是关于契约 API 和无契约 API,你是怎么看的?

JN: 我们可以看到超媒体有很大的潜力,但是到目前为止的推动力还是很有限。超媒体的问题在于采用情况。如果能够被广泛采用,我们可能会看到在 API 的使用方面会有快速的增长,但是契约的作用依然存在,它促成了校验、自动化测试以及工具。如果没有更好的工具支持,这种状况还会持续下去。但是有一些很优秀的人正在完善工具的功能,所以我们将来会看到它的进展。

InfoQ: 针对基于 blueprint 的 API 实现,你最近建立了Dredd 工具进行自动化测试。在 API 设计和开发方面,你似乎在尝试特有的工作流程。能描述一下吗?

JN: 在过去的十年间,软件开发有了一定的转变,从传统、静态的瀑布设计转变为更为敏捷的迭代。在敏捷中,我们看到了自动化测试、代码覆盖率以及持续集成这样的事情。但是在 API 和接口契约方面,我们看起来依然处于 1999 年代——预先设计、规模宏大的开发工程、陈旧的文档、没有代码覆盖率、没有持续集成。在 Apiary,我们正在试图改变这一点。

在这方面,Dredd 就是一个很好的例子。所有的开发人员都知道单调的、易出错的手工任务应该自动化执行。确保 API 文档处于最新的状态就是一项这样的任务。每个人都讨厌维护文档。借助于 Dredd,我们可以将代码覆盖情况转移到 API 文档之中,这种方式能够与任何已有的持续集成提供商兼容。

InfoQ: 开发人员的参与(engagement)看起来是 API 采用和成功的“秘籍(secret sauce)”。在开发人员的参与方面,每个人所缺失的是什么呢?

JN: 对可用性以及授权的关注依然是很少的。如果你看一下所有成功的 API 项目(以及更普遍来讲,以开发人员为中心的公司),它们的产品中都有很强大的品牌、很好的用户体验,它们允许用户所做的事情超出了用户最初的想象。这不是火箭技术,但是更加难以重新创造。设身处地为用户着想并不是很容易获得或通过训练就能得到的技能。这就是为什么 Apiary 的很多 API 设计会将相关人员聚集在一起:API 设计人员、API 开发人员以及 API 使用人员,创造一个环境让这些人很容易地进行协作。

InfoQ:Apiary 有 25,000 在开发的 API,你有没有规划利用一下这个市场地位,比如说创建 API 市场或仓库?

JN: 这个数字每周都在增长,所以很难进行精确统计。我们有 35,000 个 API,并且这一数字还在攀升。就在一年前,行业分析还曾经严肃地讨论世界上的 API 数量一共是 50,000 或 80,000。现在我们知道,这个数字要大得多得多。尽管 Apiary 的快速增长只是过去 12 个月内的事情,但是行业内的大多数人都在使用机构提供的或自定义的工具。这里面还有很大的成长空间。

我们只关注一件事——只做我们能做好的——那就是帮助开发人员的工具。API 市场或仓库的理念看起来很吸引人,但是我们并没有看到它能够带来的附加价值。

Apiary Inc. 总部位于旧金山,工程人员位于捷克共和国的布拉格。它由 Jakub Nesetril 和 Jan Moravec 创建,并在 2012 年底发布了 API 设计平台的公测版,这是一个创新性的产品。到目前为止,Apiary 已有超过 35,000 个 API,这是世界范围内最大的一个 API 集合。它的早期客户是 Akamai 或 GoodData 的开发人员门户。我们最近与 Jakub Nesetril 就 API 设计、描述、工具以及测试进行了交流。

原文英文链接:The Human Aspects of API Design: An Interview with Apiary's Jakub Nesetril

测试语言 & 开发架构