RESTful API 应该有模式吗？
Should a RESTful API have a schema?
最近有人告诉我，一个合适的 RESTful API 应该为它接受的资源表示定义一个模式 returns。例如 XSD 对应 XML，JSON 架构对应 JSON。
然而在我经历过的所有关于 REST 的书籍和文章中，这一点似乎不仅突出，甚至没有提到。
有人可以提供一些权威资源，以阐明我们在开发 RESTful API 时是否应该提供模式吗？
您应该为使用它的人记录您的 RESTful API。该架构更具体地针对返回的每种数据格式，这可能会有所帮助。以下是很好地定义方法和响应格式的示例 API 引用：
The Google Maps Geocoding API（JSON 和 XML）
CloudFlare API documentation v4
我看到的大部分是记录的请求方法，其中显示了响应示例和一个解释预期内容的图表（通常不是一个正式的模式）。让它对人类有意义。
您必须定义请求和响应接口并将其传达给您的 RESTful API 以某种方式 所以呼叫者知道您对请求的期望以及他们对响应的期望。
RESTful API：架构与其他接口定义
无论您使用 schema（XSD、JSON Schema 等），还是某些 other形式（自然语言、示例等）或定义接口的某种组合由您决定。这里有一些 因素 可以帮助您做出决定：
您将如何使用约定well-known。
Schema: XSD 是许多行业使用的 W3C 标准； JSON 架构是 well-known 替代 XSD 的 JSON。
其他： 自然语言和示例是可行的并且非常有帮助，尽管常常含糊不清或不完整。
您的社区最喜欢哪个公约。
架构： XSD 尤其容易受到已经投资开发其行业标准 XSD 的社区的赞赏。
其他：自然语言和例子容易被新人欣赏
您将使用的验证过程的自动化程度如何。
架构： XSD 和 JSON 架构提供 off-the-shelf，自动验证。
其他：自然语言和示例需要特别的验证工作。
您将使用的接口类型的紧密程度或松散程度。
Schema: XSD 和 JSON 可以表达一系列类型特异性，但在需要详细类型特异性时表现出色。
其他：自然语言和示例可以传达类型要求，尽管通常不准确。
其他RESTfulAPI注意事项
最后，请注意，您将做出进一步的决定 超越架构与 non-schema:
- 随着时间的推移，您将如何对界面进行版本控制。
- 什么HTTP URL结构、方法、响应码等
你会用到。
- 是否在使用 Swagger, RAML, Apiary, Apigee 或其他 API 框架时管理所有这些注意事项。
除了模式与其他接口定义决策之外，这些都是 REST API 与服务调用者通信的重要部分。
它们是可选的。如果您需要 fine-grained 过滤用户请求并同时考虑内容的语法和语义，您可以使用它。
- 这里有一个 RFC 指南提到了 XML 架构。
https://www.rfc-editor.org/rfc/rfc3470
"XML 架构（在 [41] 和 [42] 中定义）提供了额外的功能，以允许对允许的协议语法和数据类型规范进行更严格和更精确的规范。"
- 这是 JSON 架构的 IETF 草案：
https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04
"JSON 模式为给定应用程序需要哪些 JSON 数据以及如何与之交互提供了契约。JSON 模式旨在定义验证、文档、 JSON数据的超链接导航和交互控制。
如您所见，IETF 并未接受此作为 RFC（它仍是草案）。他们认为这对于像 JSON 这样的简单协议来说太多了。然而，许多开源项目都依赖于此草案。
最近有人告诉我，一个合适的 RESTful API 应该为它接受的资源表示定义一个模式 returns。例如 XSD 对应 XML，JSON 架构对应 JSON。
然而在我经历过的所有关于 REST 的书籍和文章中，这一点似乎不仅突出，甚至没有提到。
有人可以提供一些权威资源，以阐明我们在开发 RESTful API 时是否应该提供模式吗？
您应该为使用它的人记录您的 RESTful API。该架构更具体地针对返回的每种数据格式，这可能会有所帮助。以下是很好地定义方法和响应格式的示例 API 引用：
The Google Maps Geocoding API（JSON 和 XML）
CloudFlare API documentation v4
我看到的大部分是记录的请求方法，其中显示了响应示例和一个解释预期内容的图表（通常不是一个正式的模式）。让它对人类有意义。
您必须定义请求和响应接口并将其传达给您的 RESTful API 以某种方式 所以呼叫者知道您对请求的期望以及他们对响应的期望。
RESTful API：架构与其他接口定义
无论您使用 schema（XSD、JSON Schema 等），还是某些 other形式（自然语言、示例等）或定义接口的某种组合由您决定。这里有一些 因素 可以帮助您做出决定：
您将如何使用约定well-known。
Schema: XSD 是许多行业使用的 W3C 标准； JSON 架构是 well-known 替代 XSD 的 JSON。
其他： 自然语言和示例是可行的并且非常有帮助，尽管常常含糊不清或不完整。
您的社区最喜欢哪个公约。
架构： XSD 尤其容易受到已经投资开发其行业标准 XSD 的社区的赞赏。
其他：自然语言和例子容易被新人欣赏
您将使用的验证过程的自动化程度如何。
架构： XSD 和 JSON 架构提供 off-the-shelf，自动验证。
其他：自然语言和示例需要特别的验证工作。
您将使用的接口类型的紧密程度或松散程度。
Schema: XSD 和 JSON 可以表达一系列类型特异性，但在需要详细类型特异性时表现出色。
其他：自然语言和示例可以传达类型要求，尽管通常不准确。
其他RESTfulAPI注意事项
最后，请注意，您将做出进一步的决定 超越架构与 non-schema:
- 随着时间的推移，您将如何对界面进行版本控制。
- 什么HTTP URL结构、方法、响应码等 你会用到。
- 是否在使用 Swagger, RAML, Apiary, Apigee 或其他 API 框架时管理所有这些注意事项。
除了模式与其他接口定义决策之外，这些都是 REST API 与服务调用者通信的重要部分。
它们是可选的。如果您需要 fine-grained 过滤用户请求并同时考虑内容的语法和语义，您可以使用它。
- 这里有一个 RFC 指南提到了 XML 架构。
https://www.rfc-editor.org/rfc/rfc3470
"XML 架构（在 [41] 和 [42] 中定义）提供了额外的功能，以允许对允许的协议语法和数据类型规范进行更严格和更精确的规范。"
- 这是 JSON 架构的 IETF 草案： https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04
"JSON 模式为给定应用程序需要哪些 JSON 数据以及如何与之交互提供了契约。JSON 模式旨在定义验证、文档、 JSON数据的超链接导航和交互控制。
如您所见，IETF 并未接受此作为 RFC（它仍是草案）。他们认为这对于像 JSON 这样的简单协议来说太多了。然而，许多开源项目都依赖于此草案。