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描述格式、和跟API定义格式、和之间是有很大区别的。大多数人认为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的这两种元数据(定义和描述)之间是互补关系。
来源: http://www.infoq.com/cn/articles/document-description-formats-web-apis