REST 客户端 API 数据类型答案

【问题标题】：REST client API data typesREST 客户端 API 数据类型
【发布时间】：2014-08-21 05:17:08
【问题描述】：

我的基本假设是，对于 SOAP Web 服务，提供的 WSDL 将包含描述发送和接收数据类型的 XSD。在使用 Java 开发客户端时，可以使用 wsimport 等工具生成与 WSDL 元素相对应的类，尤其是复杂数据类型。这使 SOAP 客户端的开发人员无需创建表示返回类型（和/或复杂参数）的类。

相比之下，我通常没有见过 REST api -

WSDL 2.0 http://www.ibm.com/developerworks/webservices/library/ws-restwsdl/
WADL http://www.w3.org/Submission/wadl/
（如果服务器和客户端都是 Java）只提供服务器端使用的相同 JAXB 类
XSD

所以我的问题是 - 作为 REST 服务器端 api 的作者，向客户端提供相关数据类型的最佳方式是什么？

【问题讨论】：

REST 不需要任何文档 - 根据定义，生成的数据应该足以让客户端进一步导航或处理数据，否则您没有纯“REST”，而是使用 HTTP 的 RPC。另一方面，这取决于您的情况，例如正在制作一个 JSON 模式。
大概一个正在查询书店并列出书籍的客户可能希望将返回值作为书籍对象的集合来处理。这是一个公平的假设吗？如果是这样，缺少任何列出的选项，他们将需要实现自己的 Book 类......就像其他所有客户一样。因此，生成的数据本身“足以让客户进一步导航或处理数据”。我只是为了让处理更方便。
这是self documentation example。客户端只需要一个底层 HTTP 库即可开始使用 REST 服务。查看返回的结构是什么，并使用您选择的编组器将它们编组为对象（例如来自 google 的 gson for json）。
HATEOAS 看起来是关于发现后续操作和链接资源的。我认为这是一个不同的话题（可能是错误的）。让我尝试更简单地问...如果我想通过 REST 接口创建一个新对象，这个对象将具有属性。如果没有我列出的选项，我怎么知道这些属性的名称和数据类型？
刚刚发现这个问题stackoverflow.com/questions/22427747/…。答案意味着 xhtml 响应提供了一个带有属性和数据类型的表单。这接近我正在寻找的（仍然不能轻易地从中生成类）。但这种方法是任何记录标准的一部分吗？

标签： java rest wsdl

【解决方案1】：

由于 REST API 的用户肯定是开发人员，因此没有一个答案。作为开发人员，我认为使用我最喜欢的编程语言的客户端库（由 API 的创建者开发）是最佳选择。

您已经在文档中提到了 WADL，但也有：

Swagger：可能是最成熟、功能最丰富的 REST API 文档方法。它包括一个可嵌入的 API 浏览器。
RAML：基于 YAML 的 REST API 规范标准。围绕此创建了多个项目，例如一个（实验性）JAX-RS 生成器，包括带注释的 Jackson 类或 raml2html 转换器。

两种选择都支持 Json Schema 的 XSD。通过使用其中之一，您应该能够创建对所有可能的 API 用户都有帮助的文档。

【讨论】：

带有 codegen 模块的 Swagger 似乎可以工作，为客户端提供数据类型并能够生成客户端代码。如果有更广泛的方法（就像 SOAP 的 wsimport 一样），我会更高兴，但很多人似乎都认为没有理由在客户端代表您的实体。