一个RESTful API应该有一个模式吗？

Question

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

然而，在我查阅过的所有关于REST的书籍和文章中，似乎都没有明确提及这点。

可以有权威的资源来澄清我们在开发RESTful API时是否应该提供模式吗？

- Sebastian K

Answer 1

You have to define and communicate the request and response interfaces to your RESTful API in some way so that callers know what you expect in the request and what they can expect in a response.

RESTful API: Schema vs Other Interface Definition

Whether you use a schema (XSD, JSON Schema, etc), or some other form (natural language, examples, etc), or some combination to define your interfaces is up to you to decide. Here are some factors to inform your decision.

• 您将使用多么著名的约定。

  模式：XSD是W3C标准，被许多行业使用；JSON Schema是针对JSON的众所周知的替代品。

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

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

  模式：特别是那些已经投资于为其行业开发标准XSD的社区更倾向于欣赏XSD。

  其他：新手更倾向于欣赏自然语言和示例。

• 您将使用多么自动化的验证过程。

  模式：XSD和JSON Schema都提供现成的自动化验证。

  其他：自然语言和示例需要进行临时努力以进行验证。

• 您将使用多么紧密或松散的接口。

  模式：XSD和JSON可以表达一系列类型特定性，但在需要详细的类型特定性时表现出色。

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

其他需要考虑的RESTful API问题

最后，需要注意的是你将需要做出进一步的决策：不仅是关于模式与非模式的选择：

• 接口随时间如何进行版本控制。
• 你将使用哪种HTTP URL结构，方法，响应代码等等。
• 是否使用Swagger, RAML, Apiary, Apigee或其他API框架来管理所有这些问题。

除了模式和其他接口定义决策外，所有这些都是将您的REST API传达给服务调用者的重要部分。

- kjhughes

Answer 2

你应该为使用 RESTful API 的人编写文档。结构更具体，适用于每个返回的数据格式，这可能会很有帮助。以下是定义方法和响应格式的示例 API 参考资料： Google Maps 地理编码 API (JSON 和 XML) SoundCloud HTTP API 参考 CloudFlare API 文档 v4 Twitter 搜索 API 大多数情况下，我看到的是请求方法有响应示例并显示一个图表来解释期望（不太常见一个正式的结构）。使其对人类有意义。

- Christopher Stevens

Answer 3

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

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

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

"XML Schema（在[41]和[42]中定义）提供了额外的功能，以允许更紧密、更精确地指定允许的协议语法和数据类型规范。"

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

"JSON模式为给定应用程序所需的JSON数据以及如何与其交互提供了合同。JSON模式旨在定义JSON数据的验证、文档、超链接导航和交互控制。"

"正如您所看到的，IETF没有将此作为RFC接受（它仍然是一个草案）。他们认为这对于像JSON这样的简单协议来说太过复杂。然而，许多开源项目依赖于这个草案。"

- skwon