RESTful API是否应该具有架构？

Question

最近有人告诉我,一个正确的RESTful API应该为它接受和返回的资源表示定义一个模式.例如,XSD for XML和JSON Schema for JSON.

然而,在所有关于REST的书籍和文章中我都经历过,这似乎从未像现在这样突出,甚至提到过.

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

Answer 1

您必须以某种方式定义和响应RESTful API的请求和响应接口,以便呼叫者知道您对请求的期望以及他们在响应中可以期待的内容.

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

您是否使用模式(XSD,JSON模式等)或其他形式(自然语言,示例等)或某种组合来定义接口由您决定.以下是一些可以为您做出决定的因素:

• 您将使用的会议的知名度如何.

  架构: XSD是许多行业中使用的W3C标准; JSON Schema是XSD for JSON的众所周知的替代品.

  其他:自然语言和示例是可行且非常有用的,尽管通常含糊不清或不完整.

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

  架构: XSD尤其受到已经投资为其行业开发标准XSD的社区的青睐.

  其他:自然语言和例子往往受到新人的欢迎.

• 您将使用的验证过程的自动化程度.

  架构: XSD和JSON Schema都提供现成的自动验证.

  其他:自然语言和示例需要临时努力进行验证.

• 您将使用的接口的紧密或松散类型.

  模式: XSD和JSON可以表达一系列类型特异性,但在需要详细的类型特异性时会发光.

  其他:自然语言和示例可以传达类型要求,尽管通常是不精确的.

其他RESTful API注意事项

最后,请注意,除了架构与非架构之外,您还需要做出进一步的决策:

• 如何随着时间的推移对接口进行版本控制.
• 您将使用哪种HTTP URL结构,方法,响应代码等.
• 是否在使用Swagger,RAML,Apiary,Apigee或其他API框架时管理所有这些注意事项.

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