rest - RESTful API 应该有模式吗？

Question

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

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

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

Answer 1

您必须定义请求和响应接口(interface)并将其传达给您的 RESTful API 不知何故以便调用者知道您对请求的期望以及他们对响应的期望。

RESTful API:模式与其他接口(interface)定义

无论您使用 架构 (XSD、JSON Schema 等)，或一些 其他 形式(自然语言、示例等)或某种组合来定义您的界面由您决定。以下是一些有助于您做出决定的因素:

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

架构: XSD 是许多行业使用的 W3C 标准； JSON Schema 是用于 JSON 的 XSD 的著名替代方案。

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

您的社区将最欣赏哪种公约。

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

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

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

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

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

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

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

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

其他 RESTful API 注意事项

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

随着时间的推移，您将如何对接口(interface)进行版本控制。

什么 HTTP URL 结构、方法、响应代码等
你会用。

是否在使用 Swagger 时管理所有这些注意事项, RAML , Apiary , Apigee ，或其他 API 框架。

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