13

我们正在设计一个相当复杂的 REST API，其中大部分 I/O 是具有特定结构的 JSON 编码对象。我们发现的一个挑战是以一种使客户更容易发布正确输入和处理输出的方式记录 API。由于输入和输出的数据都需要相当复杂的 JSON 对象，因此客户端开发人员经常会引入与 I/O 对象结构相关的错误。

现在有了所有的 JSON Web API，我希望有一个通用的解决方案，但我很难找到一个。我查看了json-schema，它是一个 json-validation 模式，但 IETF 草案和实现似乎都相当不成熟（即使它们已经存在了一段时间，这不是一个好兆头）。

Protocol Buffers和Apache Avro提供了一种稍微不同的方法，其中模式不用于验证，但实际上需要用于消息的编码/解码。在这 2 个中，Avro 的文档和实现似乎相当有限。ProtoBuf 似乎更好，但我不确定这是否真的适合在浏览器中使用来调用 JSON api？

现在我开始怀疑我是否从正确的角度看待这个问题。是否有其他方法可以使我的 API 更加强类型？还是对 JSON REST/RPC API 的正式描述违背了使用 JSON 的目的？

编辑：在这个主题之后的 6 个月，我们发现了mongoose，这与我们正在寻找的非常接近。

4

4 回答 4

8

下面是我从 Douglas Crockford 收到的电子邮件回复。

我不相信模式可以替代输入验证。有些属性无法从语法中验证。我认为这是 XML 出错的原因之一。

如果您的格式太复杂，那么我会考虑简化它们。

于 2012-06-01T02:55:40.807 回答
4

这样的系统存在，我是其中之一的作者。它被称为Piqi-RPC，它通过 HTTP 对 RPC 样式 API 的输入和输出参数进行基于 IDL 的验证。

它支持 JSON、XML 和 Google 协议缓冲区作为 HTTP POST 请求的输入和输出的数据表示格式。客户端可以选择使用这三种格式中的任何一种，并使用标准Accept和Content-TypeHTTP 标头指定他们的选择。

所以，是的，理论上，你正在寻找正确的方向。但是，目前 Piqi-RPC 仅支持在 Erlang 中编写服务器，如果您使用不同的堆栈，它对您来说并不是很有用。我听说 Apache Thrift 也支持 JSON over HTTP 传输，但我没有检查。我知道的另一种类似系统（也适用于 Erlang）称为UBF。我听说过可以根据协议缓冲区规范（例如http://code.google.com/p/protostuff/）解析和验证 JSON 的 Java 库。

这个想法本身远非新事物，但在实践中并没有多少系统能够接近它。这是一个具有挑战性的问题。

从历史上看，IDL 用于接口定义和二进制数据序列化，而不是用于验证后来出现的动态数据交换格式（例如 XML 和 JSON）。Sun-RPC IDL 和 CORBA IDL 属于第一类。WSDL 将是涵盖这两个领域的少数示例之一，但它是一项糟糕的技术，对于大多数现代系统来说，这将是一个糟糕的选择。此外，还有许多模式语言（也称为 DDL——数据定义语言），其中大多数是高度专业化的，并且只使用一种表示格式，例如 XML 或 JSON 模式。其中很少有稳定的实现。

Piqi 项目和基于它的 Piqi-RPC 是围绕几个相当简单的实现构建的：

  • DLL 不必明确地绑定到任何特定的数据表示格式或围绕它构建。相反，这种语言可以相当普遍，涵盖广泛的实际用例（例如跨语言数据序列化和数据验证）和数据格式（例如 JSON、XML、Protocol Buffers）。

  • 用于 RPC 式通信的 IDL 可以实现为通用 DDL 之上的一个薄的、主要是语法层。

  • 这样的 IDL 和接口规范可以与传输无关。

说到基于 HTTP 的 REST 风格的 API 与基于 HTTP 的 RPC 风格的 API。

使用 RPC 样式的 API，服务开发人员或自动化系统必须验证三件事：函数名称（根据某些服务命名方案）、输入以及（如果您选择）输出。

对于 REST 风格的 API，人们会无缘无故地陷入困境。现在，他们有更多的东西需要验证：任意复杂的 URL 语法，包括编码在 URL 段中的动态参数（适用于所有 HTTP 方法）和 URL 查询字符串（仅适用于 HTTP GET 方法）、HTTP 方法对应关系（是否应该是 GET , POST, PUT, DELETE 等），一些参数到达那里时的 HTTP 正文（有时他们为 JSON 和 XML 表示的参数手动执行两次），自定义 HTTP 标头，以及单独的服务文档。想象一下支持所有这些的 IDL！

于 2012-06-04T06:40:44.590 回答
2

XML 在很多方面更适合 RESTful 服务。它具有本地链接（<link href=适用于所有HATEOAS粉丝）、本地语言支持（lang="en"）和出色的生态系统。

它也更适合未来的证明和未来的 API 重构。转换这个：

<profile>
    <username>alganet</username>
</profile>

支持更多用户名：

<profile>
    <username>alganet</username>
    <username>alexandre</username>
</profile>

在不破坏使用 XML的现有客户端的情况下更简单。JSON 很难做到这一点。

如果您真的需要 JSON，那么 JSON-Schema 是您的最佳选择。它不成熟，但我不知道关于那个案子有什么更好的。也许您的消费者可以在 XML 和 JSON 之间进行选择，因此他们可以使用 Content Negotiation 在小型有效负载 (JSON) 或 RESTful candies (XML) 之间进行选择。

于 2012-06-01T03:08:07.430 回答
0

我会说你最后一个问题的答案是肯定的。如果您需要一种方法来约束和记录 JSON“模式”，为什么不首先使用 XML？解析并没有那么难，并且能够为它强制执行模式是一个很大的优势。

于 2012-05-30T06:58:50.783 回答