RESTful API应该有模式吗？

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

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

---

有人能提供一些权威性的资源来澄清我们在开发RESTful API时是否应该提供模式吗？

您应该为使用RESTful API的人记录您的RESTful API。模式对于返回的每种数据格式都更加具体，这可能会有所帮助。下面是一些API引用示例，它们很好地定义了方法和响应格式：

（JSON和XML）

---

我看到的大部分是用响应示例记录的请求方法，以及解释预期内容的图表（通常不是一个单独的正式模式）。让它对人类有意义。

您必须以某种方式定义请求和响应接口，并将其与RESTful API通信，以便调用者知道您在请求中期望什么以及他们在响应中期望什么

RESTful API：模式与其他接口定义 是否使用模式（XSD、JSON模式等），或某种其他形式（自然语言、示例等），或某种组合来定义接口，由您决定。以下是一些影响您决定的因素：

• 你将使用的惯例的知名度
  模式：XSD是一种W3C标准，在许多行业中使用；JSON模式是众所周知的XSD for JSON的替代方案
  其他：自然语言和示例是可行的，并且非常有用，尽管它们常常模棱两可或不完整

• 您的社区最欣赏哪种习俗
  Schema:XSD尤其受到已经投资开发行业标准XSD的社区的青睐
  其他：自然语言和示例往往会受到新来者的欣赏

• 您将使用的验证过程的自动化程度
  模式：XSD和JSON模式都提供现成的自动验证
  其他：自然语言和示例需要特别努力进行验证

• 您将使用的接口类型有多紧密或松散
  模式：XSD和JSON可以表达一系列类型特异性，但当需要详细的类型特异性时，它们会发光
  其他：自然语言和示例可以传达类型要求，尽管通常不精确

其他RESTful API注意事项 最后，请注意，除了模式与非模式，您还有更多的决策要做：

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

---

这些都是REST API与服务调用者通信的重要部分，此外还有模式与其他接口定义决策。

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

这里有一个RFC指南提到了XML模式

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

以下是JSON模式的IETF草案：

“JSON模式为给定应用程序所需的JSON数据以及如何与之交互提供了约定。JSON模式用于定义JSON数据的验证、文档、超链接导航和交互控制。”

如您所见，IETF并未将其视为RFC（它仍然是草案）。他们认为这对于JSON这样的简单协议来说太过分了。然而，许多开源项目依赖于这个草案