机器可读格式的REST服务示例

Question

我看到的大多数REST接口都描述了一个简单的网页，描述了URL，方法，接受的输入和返回的结果。例如Amazon S3或Twitter API文档。

人类可读对于亚马逊或Twitter来说显然已经足够好了。但是有没有公司以机器可读的格式描述REST API？如果是，那是哪些？

WSDL 2.0声明为capable of describing REST。显式创建WADL用于描述REST服务。 WSDL 2.0和WADL似乎都有一个相当小的跟随atm，它似乎是创建和维护描述文档的努力的回报。通过识别现实生活中的例子，基本上可以验证或否定这一假设。

您是否使用WSDL / WADL来描述您的服务？您是否依赖WSDL / WADL来消费他人的服务？您的选择工具目前是否支持？是否有可以使用的广泛使用的REST服务示例，这些示例以机器可读格式详细说明？

Answer 1

是的，你应该。您将能够使用一组支持WADL的工具生成客户端代码，测试和文档。可以找到一些示例here。另外，我认为你应该坚持使用WADL而不是WSDL 2.0，因为它不那么冗长，而且更简单（恕我直言）。事实上，在WADL中，您只需使用WADL XML语法准确描述用户在文档页面上看到的内容。顺便说一句，这就是为WADL编写基于XSLT的文档生成器这么容易的原因。

Answer 2

以下是我个人的意见：

我认为WADL类似于html页面的站点地图。站点地图在理论上被认为是一种很好的做法，但很少实施，甚至很少被人们使用。

我认为原因很简单 - 在网站上闲逛并推出具有战略意义的按钮通常比浏览复杂的地图更有价值。

REST API方法不应要求正式描述。因此，如果API经过深思熟虑的创建，只需遵循“主页”RESTful资源的战略性放置uri链接即可轻松发现所有资源。

Answer 3

机器可读的REST API定义有什么好处？

REST的重点是API相对简单易懂。自然语言很适合这一点。

当您说“API定义”时，如果您的意思是“API类型定义”，那么提供元数据可能会有一些价值。但是，这只是API定义的一部分。

拥有“机器可读”的API可以轻松地重复API源代码，违反DRY原则。

编写REST动词的内容和URI的英文描述通常更简单。发送通过JSON（或YAML或JAXB）编组的类型作为源代码。这是完美的机器可读API - 消息对象类的实际工作源。

Answer 4

这里有鸡肉/鸡蛋的现象。没有生产或消费它的工具，WADL就没用了。除非网站发布WADL，否则这些工具无用。等。

对我来说，亚马逊模式运作良好。根据您的受众，您将获得更多回报以生成样本，包括剪切样本对话框（在线上看起来像request1，响应1，然后是请求2，响应2等），以及vvarious中的代码对你很重要的语言。如果要转到机器可读定义，则可以使用XSD（如果它是XML消息格式）。显然这不是WADL，但加上你的英文描述，它可能为开发人员提供一些额外的实用工具。

Answer 5

WSDL（和WADL以同样的方式）最流行的用法是代码生成。它肯定有助于加速开发，但没有什么可以取代普通的旧文档。对于人而不是机器。