最近有人告诉我，一个正确的RESTful API应该为它接受和返回的资源表示定义一个模式。例如，XSD for XML和JSON Schema for JSON。
然而，在所有关于REST的书籍和文章中，我经历过这一点，从未像现在这样突出，甚至提到过。
有人可以提供一些权威资源，以澄清我们是否应该在开发RESTful API时提供架构？
答案 0 :(得分：13)
您必须定义请求和响应接口并将其与RESTful API 以某种方式 进行通信，以便呼叫者知道您对请求的期望以及他们对响应。
是否使用架构（XSD，JSON架构等）或某些其他表单（自然语言，示例等）或某些组合来定义接口由您决定。以下是一些因素以告知您的决定：
您将如何使用会议。
架构： XSD是许多行业中使用的W3C标准; JSON Schema是XSD for JSON的众所周知的替代方案。
其他：自然语言和示例是可行且非常有用的，但通常含糊不清或不完整。
您的社区最喜欢哪种约定。
架构： XSD尤其受到已投资为其行业开发标准XSD的社区的青睐。
其他：自然语言和例子往往受到新人的欢迎。
您将使用的验证流程的自动化程度。
架构：XSD和JSON架构都提供现成的自动验证。
其他：自然语言和示例需要临时努力进行验证。
您使用的界面的紧密程度或松散程度。
架构： XSD和JSON可以表达一系列类型特异性，但在需要详细的类型特异性时会发光。
其他：自然语言和示例可以传达类型要求，尽管通常不精确。
最后，请注意，您还需要做出进一步的决定，使超越架构与非架构：
除了架构与其他接口定义决策之外，这些都是REST API与服务调用者通信的重要部分。
答案 1 :(得分：1)
您应该为使用它的人记录您的RESTful API。模式对于返回的每种数据格式更具体，这可能会有所帮助。以下是很好地定义方法和响应格式的示例API引用：
The Google Maps Geocoding API（JSON和XML）
CloudFlare API documentation v4
我所看到的主要是请求方法，其中显示了响应示例，以及一个解释期望内容的图表（通常不是一个正式的架构）。让它对人类有意义。
答案 2 :(得分：1)
它们是可选的。如果您需要对内容的语法和语义进行细粒度的用户请求过滤，请使用它。
https://tools.ietf.org/html/rfc3470
＆＃34; XML Schema（在[41]和[42]中定义）提供了额外的功能，可以更准确，更精确地指定允许的协议语法和数据类型规范。＆＃34;
＆＃34; JSON Schema提供了给定应用程序所需的JSON数据以及如何与之交互的合同。 JSON Schema旨在定义JSON数据的验证，文档，超链接导航和交互控制。＆＃34;
正如您所看到的，IETF并未接受此作为RFC（它仍然是草案）。他们认为这对于像JSON这样的简单协议来说太过分了。然而，许多开源项目都依赖于这个草案。