我应该使用WADL描述我的RESTful API吗？

我将着手进行一个广泛使用正确的RESTful方法的项目。也就是说，它使用HATEOAS并以允许客户端进行常规探索的方式提供资源。

我想确保以一种允许以多种语言自动生成客户端应用程序的方式提供对端点的描述。我了解对于基于SOAP的Web服务，我可以使用WSDL，并且显然有WSDL2提供了与REST一起使用的HTTP动词的更大定义。但是，我看到许多关于它的实用程序的文章来回摆动。

因此，我应该使用WADL来允许外部代码生成器快速为我的Web应用程序构建客户端，还是期望有更好的标准？

我的建议是不要打扰。WADL尚未得到广泛采用。有关堆栈溢出问题，请参见此问题，并且有一些强烈的观点认为它与您描述的“适当的” REST不太匹配，如此处另一个堆栈溢出问题所示。

WADL描述的构建非常耗时（并且大多是手动的），并且增加了HATEOAS可以避免的脆弱性-即，您将具有一些定义明确的入口点，但是确切地说，您的客户如何进行则取决于不透明的链接，而不是预定义的链接'合同'。

这并不是说您应该完全摆脱文档，架构定义等，尽管RESTifarian范围的尽头表明您可以进行不需要它们的如此高级别的自我描述。在实践中，我还没有发现这种情况。一些扎实的示例应该是开发人员不熟悉的全部。并为您自己的API敲几个客户端以进行尝试（通过JQuery足够容易）。这将为您是否在构建耗材提供一个很好的指示。

超文本应用语言是该领域的一个很好的信息来源。我发现其中有些重量级，但是邮件列表上的辩论是美好而当前且相关的。

希望对您有所帮助。

REST接口的状态不是由交互式浏览器驱动的，而是非常不好的。HATEOAS是一个很好的原则，但是它导致的界面非常以人为本，并且往往导致用户界面的负担加诸于服务开发人员（他们通常非常忙于使服务本身正常工作）。

WADL本身不是很好。它并没有真正捕捉到服务的语义，不足以使事情变得可行。当然，这通常是一个难题。WSDL也很少公开足够的信息，而在这个问题上付出了更多的努力（可以附加足够的信息，但是几乎没有人这样做）。

然而，这表明我的一位同事已经花了几个月的时间在一个使用REST接口连接到服务的库上工作，并且WSDL描述的相同服务的接口^[*]可以在几秒钟内自动达到几乎相同的质量；其余的时间大约是写包装类的一天。我的直觉（基于有限的样本量）是，您无法摆脱复杂服务中的所有脆弱性，因为服务的语义会随着时间的推移而不可避免地发展，并且REST更好地为人类提供了接口，而SOAP则更适合于接口库（几乎所有值得注意的语言都有不错的WSDL / SOAP客户端工具）。除非您拥有两者兼得的奢侈性，否则要重点关注哪一个应取决于您最关心的一组客户。

我不会在WADL上花费很多精力，但是如果您的REST框架可以为您生成它（Apache CXF会这样做），则没有特别的理由不提供它。任何想要清除您的代码的人都将需要WSDL + SOAP。

^{[*]作为所讨论的服务的作者，我可以肯定地说两个接口都支持相同的操作-存在一个公共的基础抽象模型-并且两种接口类型都采用“自然”风格。在服务方面，使用REST轻松完成某些事情，使用SOAP轻松完成某些事情，这肯定是事实。}

在W3C已经取得了正式建议REST文档标准基于WSDL 2.0。这是IBM文章的引文：

Web服务一词通常与使用SOAP和WS *标准（例如WS-Addressing和WS-Security）的基于操作或操作的服务相关联。术语REST Web服务通常是指使用HTTP和XML的基于资源的Web服务体系结构。这些架构Web服务样式中的每一种都有其位置，但是直到最近，WSDL标准才同样支持这两种样式。WSDL 1.1 HTTP绑定不足以描述与HTTP和XML的通信，因此无法用WSDL正式描述REST Web服务。WSDL 2.0的发布是为考虑到REST Web服务而设计的，作为万维网联盟（W3C）的建议，这意味着现在已经存在一种描述REST Web服务的语言。