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
分布式云行业实践指南（2023）
业内首个分布式云行业实践方法论、工具箱。
评论