RESTful API是否应具有架构? [英] Should a RESTful API have a schema?
问题描述
最近有人告诉我，正确的RESTful API应该为其接受和返回的资源表示形式定义一个架构.例如，XML的XSD和JSON的JSON模式.
I was told recently that a proper RESTful API should define a schema for the resources representations it accepts and returns. For example XSD for XML and JSON Schema for JSON.
但是，在所有有关REST的书籍和文章中，我经历过的这件事不仅从未被提及，甚至没有被提及.
However in all the books and articles on REST I went through this has never seem not only prominent, but even mentioned.
有人可以提供一些权威性的资源来阐明在开发RESTful API时是否应该提供模式吗?
Could someone provide some authoritative resources, to clarify if we should be providing schema when developing RESTful APIs?
推荐答案
您必须定义请求和响应接口，并将其与RESTful API进行通信 ，以便调用者知道您对请求的期望以及他们对响应的期望.
You have to define and communicate the request and response interfaces to your RESTful API somehow so that callers know what you expect in the request and what they can expect in a response.
是否使用模式(XSD，JSON Schema等)或某些 other 形式(自然语言，示例等)或某种组合来定义您的接口由您决定.以下是一些因素来告知您的决定:
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是XSD for JSON的知名替代品.
Schema: XSD is a W3C standard used across many industries; JSON Schema is the well-known alternative to XSD for JSON.
其他:自然语言和示例是可行的并且非常有帮助，尽管它们常常模棱两可或不完整.
Other: Natural language and examples are viable and very helpful, although often ambiguous or incomplete.
您所在社区最喜欢的约定.
模式:XSD尤其受到已经投资为其行业开发标准XSD的社区的青睐.
Schema: XSD especially tends to be appreciated more by communities who have already invested in developing standard XSDs for their industry.
其他:新手会喜欢自然语言和示例.
Other: Natural language and examples tend to be appreciated by newcomers.
您将使用的验证过程的自动化程度.
模式: XSD和JSON模式都提供现成的自动验证.
Schema: Both XSD and JSON Schema offer off-the-shelf, automated validation.
其他:自然语言和示例需要特别的努力才能进行验证.
Other: Natural language and examples require ad hoc effort for validation.
您将使用的接口的紧密程度.
模式:XSD和JSON可以表示一定范围的类型特异性，但是在需要详细的类型特异性时才亮.
Schema: XSD and JSON can express a range of type specificity but shine when detailed type specificity is desired.
其他:自然语言和示例可以准确地传达类型要求.
Other: Natural language and examples can convey type requirements albeit often imprecisely.
最后，请注意，您将做出进一步的决定，以实现超越模式与非模式:
Finally, note that you'll have further decisions to make beyond schema vs non-schema:
- How you'll version the interfaces over time.
- What HTTP URL structure, methods, responses codes, etc you'll use.
- Whether to manage all of these considerations in using Swagger, RAML, Apiary, Apigee, or other API framework.
除了架构与其他接口定义决定之外，所有这些都是REST API与服务调用者进行通信的重要部分.
These all are important parts of the communication of your REST API to callers of your service in addition to the schema vs other interface definition decision.
这篇关于RESTful API是否应具有架构?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
