虚拟研讨会：Web API文档和描述格式-InfoQ

要点

在未来几年，Web API 文档和描述格式将成为开发者理解 Web 的基础。

通过机器浏览 Web（以及它的 API）发现内容、执行任务以及构建智能系统仍然是远大的理想。

在未来几年，围绕文档和定义格式的 API 发现将是一个持续增长的领域。

在很大程度上，文档格式仍然是以人为本，仍然需要人类来生成。

定义格式更偏向于对机器“可浏览”，有望出现机器对机器、可被机器发现、可被机器执行的 API。

大部分 Web API 就像它们的创建者一样独一无二，它们包含了各种各样的端点和 JSON 格式数据（特别是近期）。要想在这个持续膨胀的迷宫里找到一条出路是件令人沮丧的事情。不过，在过去的几年，文档和描述格式这个持续增长的领域已经有了一定程度的发展。

在这个虚拟研讨会上，我们将听到来自 Web API 领域的 4 位专家发表他们对 Web API 相关问题的看法。每位专家对 Web API 文档和描述格式的价值、好处和成本都有自己独到的看法，他们从自己实际的 Web 开发经验出发，为我们打开了不同的观察视角。有些人认为，文档和描述格式之间的界限是模糊的。有些人则认为，它们对开发者来说具有不一样（也是很重要的）的价值。不过总得来说，他们都很肯定一件事情：我们必须做点事情来帮助开发者在 Web API 的世界里辨清方向。

与会人员：

Lorinda Brandon —— 来自 Captial One DevExchange 的高级产品经理

Zdenek Nemec —— 来自 Apiary 的特定领域语言负责人、产品经理和研究组长

Ruben Verborgh —— 比利时 Ghent 大学与 iMinds 联合机构的语义超媒体研究员，Flanders 研究基地的博士后研究员

Mike Amundsen —— API Architecture、API Academy、CA Technologies 主管

InfoQ：我们为什么需要 API 描述格式？

Lorinda Brandon：事实上，我并不认为它们是“被需要”的。我们已经使用 WSDL 和 WADL 很长时间了（也许我们也应该把它们看成描述格式），如果很不幸地，你的系统需要跟 SOAP API 集成，那么你仍然可以不借助任何现代描述格式就能完成工作。所以，与其说它们是“被需要”的，不如说它们是“被期待”的。首先，它们有助于 API 功能的交互。其次，它们有助于提高 API 的使用率。

Zdenek Nemec：描述格式开启了有关 API 的结构化讨论。它们让 API 的设计更加具体化，为参与方提供了蓝图和契约。我举个“电子邮件”的例子来说明吧：

大概在四年前，我和我的朋友 Paul 着手开发一个全新的 iOS 应用，后端由一组 API 来支撑。我负责前端开发，Paul 负责服务器端开发。

有一天，我发了一封邮件给 Paul，问他我们的 API 是否具有功能“AB”和功能“C”。Paul 回复说“当然了，Zdenek，不过如果我们用功能 D 代替功能 C，我们就可以把功能 B 调整成这样……”。我接受了 Paul 的建议，并立即把调整过的内容回复给他。三天之后，我们的邮件对话里有超过 30 条的消息。确实，我们通过发送电子邮件来设计 API，而我们的设计也到了可以构建的阶段。那些邮件就是我们之间的契约，但想要从这些对话里理清头绪真的要靠运气。我们几乎无法从中获得有关 API 的清晰蓝图。

这个时候，我们意识到我们需要更好的讨论方式。

Ruben Verborgh：关于“API 描述格式”，存在着多种不同的理解，每一种理解都有自己的理由。它们大致可以被分为两类，“面向开发者的描述”和“面向机器的描述”。

面向开发者的 API 描述简化并加速了客户端开发，这要得益于文档、代码自动完成和模板代码自动生成这些特性。这类 API 描述跨越了从使用 WSDL 格式的 SOPA API，一直到现在由 OpenAPI（前身是 Swagger）和 API Blueprint 大力提倡的 HTTP API。实际上，它们在客户端和服务端之间建立了一种硬编码的契约，以此来获得编程语言无关性和对开发者的友好。

反过来，面向机器的 API 描述主要是为了让 API 更适合用在自动化客户端上。它们提供运行时的 API 解释，而不是在设计时自动生成模板代码。拿 Hydra Core Vocabulary 为例，它允许 Hydra Console 这样的客户端在运行时发现 API 所支持的资源和操作。这是很有必要的，因为机器不像人类，它们并不清楚网站是如何运作的。

Mike Amundsen：首先，我认为 API 描述领域里的一些东西需要被分离出来，它们属于“API 元数据空间”。我认为 API 描述格式 JSONHome 、 ALPS 和 APIs.json 跟 API 定义格式 Swagger（OpenAPI）、 RAML 和 API Blueprint 之间是有很大区别的。大多数人认为 Swagger/OpenAPI、RAML 和 API Blueprint 就是“API 描述”——这样理解没有什么问题，但我们要从更广的视角来看待这个问题。

Swagger 定义了 URL、资源、消息格式和单个 Web API 的其它细节。这些定义可以用来生成服务接口，有时候也可以用来生成客户端应用程序。这是因为规范里已经定义了实现细节。当然，这也会减少开发者在构建可运行 Web API 时所做的前期编码工作。

APIs.json、ALPS 和 JSONHome 做的事情不太一样，它们一般只描述接口，无法用它们来生成服务或客户端。不过可以用它们来加强对协议、媒体类型和服务语义的理解。我认为可以用 APIs.json 和 ALPS 来描述 Web API 的类（例如购物、用户管理等），而不是实现（例如 Foxycart 购物 API）。

回到你之前的问题，我认为这两种格式都是 Web 所需要的。为了得到可行的实现方案，我们需要一种方式来定义 Web API。同时，为了支持在线发现和交互，我们也需要一种方式来描述 Web API。在我看来，API 的这两种元数据（定义和描述）之间是互补关系。

InfoQ：使用描述格式是否会遏制对超媒体的需求（或者反过来）？

Zdenek Nemec：我认为，都不会。我们可能需要通过某种方式来讨论如何构建 API，而无需关心 API 的架构风格。同时，又希望在 API 描述里体现架构风格。从长远来看，对 API 架构风格的理解是 API 取胜的一个关键因素。可惜的是，现今大部分 API 描述格式都遏制了架构风格的体现，而推崇的是并非最优的范式和模式。REST（超媒体）架构风格（查看 Benjamin 关于内容协商的文章）就是一个典型的例子。

Apiary 做了一些关于 API 描述是否能够把非超媒体 API 转化成超媒体 API 的研究。我们得出的结论是，这在一定程度上是可能的，但在现今的 API 行业却行不通。

Ruben Verborgh：如果我们想让客户端在没有硬编码的情况下灵活地执行复杂操作，既需要描述格式也需要超媒体。

超媒体控件的作用是让人类或机器可以预览下一步动作的内容，并获得执行下一步动作所需要的具体信息。例如，在浏览购物网站时，可以通过各种链接和表单把物品添加到购物车里。“结算”按钮包含了处理订单的 HTTP 请求细节。所以如果我们不想在客户端硬编码 URL 和请求信息，我们需要依赖超媒体控件。

描述格式通过事先列出每个资源能够支持的操作，让客户端预览多个步骤的内容。对人类来说这不是必需的，因为人类只对即将发生的事情有所期待。例如，我们知道，购物网站在某一时刻会要求我们输入地址和账单信息（尽管我们不知道具体的顺序）。自动化客户端不会有这样的期待，所以如果要想让它们在不硬编码的情况下预览多个步骤的内容，我们必须显式地描述这些步骤。

Mike Amundsen：不会的。Web API 的具体实现是否具有（或没有）超媒体特征，跟是否用 Swagger 或 RAML 来定义 API 没有直接的联系，超媒体的使用完全独立于定义和描述格式。

我认为，直至今日，没有任何一个定义格式可以很好地支持超媒体风格的实现。我希望看到它们能更好地支持超媒体，但至少现在看来，“三大”格式使用以资源为中心的方式来定义 Web API，已然是目前最为流行的做法。

我想我们还是可以很好地利用定义格式，它们以操作为中心，使用链接和表单来定义添加、编辑、审核、分享等操作，开发者可以把这些操作元素合并到资源的响应消息里。这跟现在的 API 定义方式很不一样，我们要用<a href="...">...</a>和<form action="..." method="...">...</form>这些元素来定义 HTML 响应。但实际上我们的定义还没有达到这个层面。

InfoQ：RESTful Web 服务在没有使用描述格式的情况下已经走过很长的一段路，但现在描述格式的形势却在快速增长，是什么导致了它的增长呢？

Lorinda Brandon：我想很大程度上是因为 API 的爆发式增长。因为大量 API 的存在，开发者需要快速地从中找出适合自己的 API，更有甚者，非开发者也在这么做。产品经理在选择集成 API 时，一般不希望趟 WADL 这趟浑水。对 API 来说，它们就好像被摆在技术市场上等待出售，你把 API 描述显摆出来，它们不言自明，所以不需要再费劲地去描述功能特性。况且，基于描述的工具让它们变得更加强大，因为使用者可以通过这些工具直接获得想要的结果。

Zdenek Nemec：我认为是开发速度（还有开发成本）造成的。我的“电子邮件”故事告诉我们，API 的设计可以不需要描述格式。除了长时间的会议、堆砌的邮件和 Word 文档，还有很多更有效的的方式可以用于 API 设计。

况且，通过使用 API 描述格式，我们可以跳出框架来谈论 API。我们也因此可以避免瀑布迭代，通过快速的原型创建、测试和简洁的文档来改进 API 设计流程。

开发者和利益相关者们意识到了这一点，这也就是为什么描述格式会被越来越多的人所采用。

Ruben Verborgh：从积极的方面来看，我认为这跟客户端开发的增长趋势有关系。如果从悲观的角度看这个问题，我认为是 API 的疯狂增长和接口重用的欠缺催生了这个需求。我们现在有大量的 API 做着相似的事情，但它们的接口却非常不一样，导致每次开发都要从头做起。例如，虽然 Facebook、Twitter 和 Instagram 都支持使用图片来更新状态，但它们的接口完全不一样，造成客户端的不兼容。这么说来，（面向开发者的）API 描述也只是治标不治本，它们无法解决 API 的根本问题。API 的开发者一直在重复发明轮子，导致缺乏 API 描述的客户端开发变得很繁琐。

Mike Amundsen：造成这种情况的因素太多了，而且由来已久。2013 年，在格林维尔举行的 RESTFest 大会上，我做了一个主题为“描述一切可能性”的演讲，演讲内容提及了15 年前就已经出现的定义/ 描述格式。 WSDL 发布于 2001 年，还有其它很多面向 Web 的接口定义语言（IDL）也是从那时开始出现的。我想我们正经历着这种趋势的爆发式增长，因为有现实的需求在推动——这是一个好势头。

可以说，这些 IDL 是那个时代的宠儿。那个年代出现的定义格式主要基于 XML，而现今出现的定义格式
大都基于 JSON 或 YAML。不管序列化格式怎么变化，我认为现今大部分 Web IDL 都是在步 WSDL 和 WADL 的后尘。它们为基于 HTTP 的远程过程调用定义紧耦合、强类型的接口。除了 IDL，还有以 XMDP （2003）、 AtomSvc （2007）、 DCAP （2009）等为代表的定义格式。这些格式更像是在以一种通用的方式来描述接口，更接近 Web 的运作特点。

总的来说，我们看到了 API 元数据领域的发展，同时也看到了过去的一些探索工作在重蹈覆辙，这些工作在很长一段时间内并没有得到可观的结果。我希望我们未来会超越经典的“早期绑定”模型，朝着“晚期绑定”的方向迈进。“早期绑定”就是我们在基于 SOAP 的 WSDL 和 WADL 里所看到的那样，而“晚期绑定”的概念来自 AtomSvc、JSONHome 等。而且我认为，晚期绑定在未来会为我们带来交互性更强、重用性更高的 Web 服务。

InfoQ：你们认为 API 的文档和描述格式是个单一的个体，还是个多元的混合体？

Lorinda Brandon：这个问题问得好。刚开始我们会认为一个描述文件就够了，在某些情况下确实如此……但要实现一个 API，还有很多事情要做。在 Capital One，我们在“富文档”上投入了很多精力，“富文档”包含了使用 API 所要知道的所有信息。大部分这方面的信息并没有出现在描述文件里，比如入门指南、使用条款、品牌规范、认证模型解释、参考应用和教程等。

Zdenek Nemec：这涉及到两件事情。事实上，使用 API 描述格式的最初动机是希望在 API 文档方面可以少做一些工作。不过，潮流正在发生逆转，因为越来越多的人正在从前期设计、API 契约和快速原型中受益。

Ruhen Verborgh：它们涉及到很多方面的问题。文档不应该成为必需品，因为 API 只是网站在机器层面的表现形式，况且我们甚至都不需要网站的说明手册。我认为，在 API 可以像网站那样开始互相从对方的设计中学习之前，面向开发者的描述格式只是个过渡措施。在我看来，面向机器的描述更加成熟。

Mike Amundsen：“文档”是为人类设计的，而“描述”格式和“定义”格式是为机器设计的。我认为把它们合到一起不是一个好主意。制作出易用、可靠、强大的文档需要做大量的工作。文档把注意力集中在如何定义 HTTP URL、方法和响应码上，却忽略了那些以人类为中心、可读性强的元素，比如“入门教程”、“基本概念”和“例子”。还有其它元素，如“规约”、“扩展性”和“向后兼容能力”，它们都是很重要的，特别是对那些 Web API 使用者来说更是如此。而在 API 文档里总是看不到这些内容。

所以我认为我们需要可读性强的文档，而自动生成的文档是做不到这一点的。有个叫作“写文档社区”的组织似乎正在专注这方面的工作。我很喜欢他们的观点，并希望这个社区能够发展壮大。

同时，我认为之前提到的描述格式需要为机器做一些优化。我们可以使用这些格式实现 Web 的运行时发现。开发者可以在运行阶段为已有的服务创建组件，而不仅仅是在设计阶段或编译阶段，而这些需要设计良好的机器对机器格式。

InfoQ：我们需要为这些格式提供索引服务吗？如果是，那么开发者可以期待从中获得什么好处？

Lorinda Brandon：理想情况下，我们应该可以使用像谷歌这样的标准搜索引擎来发现 API。既然我们可以很容易地在 Web 上搜索内容，那么对于查找 API 这样的内容来说也应该是很容易的。但实际上，我们现在必须进入到 API 的目录里才能找到想要的 API。而且这些目录都是跟具体的厂商相关的，这不禁让我们对这些 API 的可靠性等方面的问题产生偏见。当然，也有可能因为在搜索框里输入了正确的关键字而幸运地撞进某个 API 的入口。几年前，Kin Lane 带领 3scale 团队尝试使用 APIs.json 来解决这个问题，我觉得实际上大家很接受他们提出的概念。

最大的挑战是如何让所有人都采用这种格式。如果 3scale 社区能够取得更多进展，那么开发者就可以更容易地发现他们需要的 API。

Zdenek Nemec：我们需要一种发布资源的方式，让资源可被发现和访问。这个跟 Berners Lee 当初创建 Web 的动机不谋而合。这是我们的终极基因。融合文化让我们习惯于在别人构建的事物上做一些改变或者添加一些新的东西进去，创造出更好的事物。

开发者很擅长做这样的事情。先是阅读学习已有代码，然后加入新的想法和可能性。对 API 描述来说，道理是一样的。如果能够把这件事情做好，让所有已知和未知的资源可被访问，并把它们连接起来，那么可能会迎来一次新的“互联网革命”，就像互联网世界过去发生的那样。

Ruben Verborgh：对面向机器的 API 描述进行索引是有意义的，它对自动化客户端来说有点像是谷歌搜索引擎。客户端应该具备查找服务的能力。而对于开发者来说，谷歌似乎已经足够强大了。

Mike Amundsen：是的，在设计和构建 Web API 时，我们要考虑如何让它们在运行时互相发现和交互而不需要人类的大量介入，所以在可重用性和可达性方面仍然有很大的提升空间。我认为这也是基于机器的描述能够发挥其价值的地方。

APIs.json 团队所做的工作对我来说是一种鼓舞。他们收集 Web API 的属性，并把它们开放出来，它们对创建组件间的连接来说是非常重要的。他们创建了一个叫作“ APIs.io ”的搜索引擎，这个搜索引擎为人们发现 API 带来很大帮助。我还看到了由他们带来的其它很多工作成果。

我和 Mark Foster、Leonard Richardson 也正在开发一个类似的项目——应用层分析原语（ALPS 规范）——为 Web API 创建与协议和媒体类型无关的高层次描述。把 APIs.json 作为服务的元数据交互手段，把 ALPS 作为服务能力的交互手段，两者的结合可以为 Web 索引化运行时发现提供强有力的支持。

InfoQ：如果一个开发者对 API 描述和文档很感兴趣并开始着手研究，那么他要从哪里开始入手呢？

Lorinda Brandon：经常有人问我这个问题，我发现这个问题很难回答。不是因为无处入手，而是因为有太多的地方可以入手了。在 API 领域，我们就是一群无话不说的人。以下的资源可以作为入门参考：

REST API 规范格式前十

RESTful API 描述语言概览（有点泛泛而谈，可能会让你摸不着头脑，不过那里有一些其它资源的链接）

API-Blueprint、RAML 和 Swagger 的另一种比较（三种最流行格式的图表化比较）

更多关于 Open API 规范的信息

Zdenek Nemec：Github 已经把 API Blueprint 视作一种语言，所以我们可以直接搜索到用这种格式描述的开源 API。其它格式也不难搜到，因为它们一般会使用一些特定的文件名。当然，API 描述（包括 API）的质量不太一样，这也是索引和 API 排名工具可以发挥作用的地方。

Ruben Verborgh：这要看他们的目的是什么。从短期来看，OpenAPI 和其它格式有助于加快开发速度。但我认为这只是临时的解决方案。从中长期来看，我希望能够看到更多客户端导向的格式可以取代开发者导向的模板代码生成和 SDK。对客户端智能生成感兴趣的开发者请移步 Hydra 社区。

Mike Amundsen：我认为那些对 API 元数据领域感兴趣的人可以把 InfoQ 系列文章“描述、发现和分析——Web API 进阶”作为入门读物。这一系列文章从多个角度给出了很多很好的观点。对接口描述语言（IDL）的历史做一个大致的了解，并对 Web 相关部分深入研究，有助于了解这个行业过去 15 年的发展状况，并发现未来的发展机会。当然，学习目前流行的定义格式（Swagger、RAML、API Blueprint）跟探索 APIs.json 和 ALPS 这样的新格式一样重要。

API 元数据领域还有很多工作要做，我有信心它将为 Web 带来更好的运行时发现和动态服务绑定能力。

总结
在未来几年，Web API 的文档和描述将成为开发者理解 Web 的基础。人们梦想的美好未来，是能够通过机器浏览 Web（还有它们的 API）发现内容、执行任务、构建智能系统，它仍然任重而道远，这也是人们从 90 年代后期一直以来的梦想。理想能否变成现实，要看架构师们和开发者们是否能够亲密合作来共同推进这项事业。

与此同时，我们还是期待能够看到这一领域出现潮涨潮落，这样才更接近客观的发展规律。虽然中间有波折，但最终的目标是不变的：缩短与成功之间的距离。

围绕文档和定义格式的 API 发现，几乎还是一个未开垦的领域，在未来几年我们将看到它的持续增长。文档格式在很大程度上仍然是面向人类的，而且需要由人类来生成。定义格式可能会越来越偏向于对机器“可浏览”，有望出现机器对机器、可被机器发现、可被机器执行的 API。

到此，所有与会者都向我们清晰地表达了这些希望、梦想和数据格式背后的想法。

与会者简介

Lorinda Brandon是 Capital One DevExchange 的高级产品经理。她拥有超过 30 年的软件开发经验，曾经在 SmartBear、RRDonnelley、EMC、Kayak Software 和 Intuit 等公司工作。她对 API 开发和软件测试有着极大的热情，在 InfoQ、Programmable Web 和 Network World 上发表过很多阐述 API 和交付高价值软件重要性的文章。

Zdenek Nemec目前是 Apiary 的特定领域语言负责人，同时也是产品经理和 API 设计团队的组长。他从事计算机系统的研究、构建和架构。他是 API Blueprint 和 MSON 的作者。他的研究领域涉及分布式系统、客户端开发和用户体验设计。他喜欢与人们互动，喜欢帮助人们去创造超乎想象的事物。

Ruben Verborgh是比利时 Ghent 大学与 iMinds 联合机构的语义超媒体研究员，也是 Flanders 研究基地的博士后研究员。他努力探索语义 Web 技术和 Web 架构属性之间的联系，他的终极目标是构建智能客户端。一直以来，他对数据连接性、REST/ 超媒体、Web API 以及相关技术很感兴趣。他是两本数据连接性相关书籍的合著者，他参与 Web 相关的国际性会议，在杂志媒体上发表 Web 相关的著作，有他参与的相关刊物超过 150 本之多。

Mike Amundsen是 API Architecture、API Academy、CA Technologies 的主管。作为 API Academy 的架构主管，Amundsen 在北美主导 API 的架构和设计工作。API 为消费者和企业带来各种各样的机会，Amundsen 负责跟同事们一起为如何更好地利用这些机会提供解决方案。在过去的 15 年里，他出版了大量关于编程的书籍和论文。他最近的一本书是跟 Leonard Richardson 合著的《RESTful Web APIs》，出版于 2013 年。他正在写一本新书——《RESTful Web 客户端》，将由 O’Reilly 于 2016 年出版。