RESTful API 应该有模式吗？

Posted 2023-03-08

【中文标题】RESTful API 应该有模式吗？

【英文标题】：Should a RESTful API have a schema?

【发布时间】：2016-04-16 13:50:57

【问题描述】：

最近有人告诉我，一个合适的 RESTful API 应该为它接受和返回的资源表示定义一个模式。例如 XML 的 XSD 和 JSON 的 JSON Schema。

然而，在我阅读过的所有关于 REST 的书籍和文章中，这一点似乎不仅突出，甚至被提及。

有人可以提供一些权威资源，以澄清我们在开发 RESTful API 时是否应该提供架构？

【参考方案1】：

您应该为使用它的人记录您的 RESTful API。架构更具体到返回的每种数据格式，这可能会有所帮助。以下是很好地定义方法和响应格式的示例 API 参考：

The Google Maps Geocoding API（JSON 和 XML）

SoundCloud HTTP API Reference

CloudFlare API documentation v4

Twitter Search API

我看到的大部分是请求方法，其中包含显示的响应示例和解释预期结果的图表（通常不是一个正式的模式本身）。让它对人类有意义。

【参考方案2】：

您必须以某种方式定义请求和响应接口并将其传达给您的 RESTful API，以便调用者知道您对请求的期望以及他们在回应。

RESTful API：架构与其他接口定义

您是否使用 schema（XSD、JSON Schema 等）或某种其他形式（自然语言、示例等）或某种组合来定义您的接口由您决定。这里有一些因素可以帮助您做出决定：

您将使用的约定有多广为人知。

Schema： XSD 是一种 W3C 标准，用于许多行业； JSON Schema 是用于 JSON 的 XSD 的著名替代方案。

其他：自然语言和示例是可行的并且非常有帮助，尽管通常模棱两可或不完整。

您的社区最欣赏哪种约定。

Schema： XSD 尤其受到那些已经投资为其行业开发标准 XSD 的社区的青睐。

其他：自然语言和示例往往会受到新手的赞赏。

您将使用的验证过程的自动化程度。

架构： XSD 和 JSON 架构都提供现成的自动验证。

其他：自然语言和示例需要特别努力进行验证。

您将使用的界面的类型是紧密还是松散。

Schema： XSD 和 JSON 可以表达一系列类型特异性，但在需要详细的类型特异性时会大放异彩。

其他：自然语言和示例可以传达类型要求，尽管通常不精确。

其他 RESTful API 注意事项

最后，请注意，您将有进一步的决定来做出超越模式与非模式：

随着时间的推移，您将如何对接口进行版本控制。 什么 HTTP URL 结构、方法、响应代码等 你会用的。 在使用Swagger、RAML、Apiary、Apigee 或其他 API 框架时是否管理所有这些注意事项。

除了架构与其他接口定义决策之外，这些都是 REST API 与服务调用者通信的重要部分。

【参考方案3】：

它们是可选的。如果您需要对用户请求进行细粒度过滤，同时考虑内容的语法和语义，您可以使用它。

这是关于 XML 架构的 RFC 指南。

https://www.rfc-editor.org/rfc/rfc3470

“XML Schema（在 [41] 和 [42] 中定义）提供了额外的功能，以允许对允许的协议语法和数据类型规范进行更严格和更精确的规范。”

这是 JSON 模式的 IETF 草案： https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04

“JSON Schema 为给定应用程序需要哪些 JSON 数据以及如何与之交互提供了一个契约。JSON Schema 旨在定义 JSON 数据的验证、文档、超链接导航和交互控制。”

如您所见，IETF 不接受它作为 RFC（它仍然是一个草案）。他们认为这对于像 JSON 这样的简单协议来说太过分了。然而，许多开源项目都依赖于这个草案。