虚拟研讨会：Web 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服务在没有使用描述格式的情况下已经走过很长的一段路，但现在描述格式的形势却在快速增长，是什么导致了它的增长呢？

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描述和文档很感兴趣并开始着手研究，那么他要从哪里开始入手呢？

总结

在未来几年，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年出版。

查看英文原文： Virtual Panel:Document and Description Formats for Web APIs