RESTful API 应该有架构吗？

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

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

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

您必须定义请求和响应接口并将其传达给 RESTful APIsomehow以便呼叫者知道您对请求的期望以及他们对响应的期望。

RESTful API：架构与其他接口定义

无论您使用schema（XSD、JSON 架构等），或一些other形式（自然语言、示例等）或定义界面的某种组合由您决定。这里有一些factors告知您的决定：

• 您将使用的约定的知名度如何。

  Schema:XSD 是跨多个行业使用的 W3C 标准； JSON Schema 是众所周知的 JSON XSD 替代方案。

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

• 您的社区最欣赏哪个大会。

  Schema:XSD 特别容易受到那些已经投资为其行业开发标准 XSD 的社区的赞赏。

  Other:自然语言和例子往往会受到新手的青睐。

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

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

  Other:自然语言和示例需要临时的验证工作。

• 您将使用的界面的类型有多紧或松。

  Schema:XSD 和 JSON 可以表达一系列类型特异性，但在需要详细类型特异性时表现出色。

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

其他 RESTful API 注意事项

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

• 随着时间的推移，您将如何对接口进行版本控制。
• 什么是HTTP URL结构、方法、响应代码等 你会用的。
• 是否在使用时管理所有这些注意事项Swagger http://swagger.io/, RAML http://raml.org/, Apiary https://apiary.io/, Apigee http://apigee.com/about/，或其他API框架。

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