Question

我正在使用W3C XML Schema（XSD）来记录资源。今天，XML表示在少数资源中返回。对我的一个资源进行POST操作需要来自客户端的XML。此资源的响应是XML。我的问题如下：

a）我应该创建一个XSD来处理请求（POST），资源的响应吗？

b）如果使用单个XSD，我应该如何区分请求（POST）和响应？一个想法围绕着：

<stream>
  <request>
    <items>xxx</items>
  </request>
  <response>
    <stuff>xxx</stuff>
  </response>
</stream>

麻烦的是，我担心请求/响应标签反映了RPC风格的方法。

c）关于POST操作，我想告知客户端XML是必需的，并且只允许在POST操作期间使用。我怀疑如果这个要求被违反我最好的选择是返回一个400错误的请求？除此之外，我认为我对XSD的唯一选择是“通过评论记录要求”？试着去了解除评论之外我应该考虑的任何XSD设计选项。当然，使用一个XSD的挑战是对GET操作的响应 - 它不需要来自客户端的XML - 将要求客户端“忽略”XML中的POST内容。

提前致谢

Answer 1

a）创建一个XSD并在该XSD中定义多个类型很好。在单个XSD中定义请求/响应对似乎是合理的。请记住XSD的消费者或用户。它会是谁？你期待吗？您的API的用户使用该XSD构建应用程序，或仅使用它服务器（接收）方面是为了在进入时验证请求？

在许多情况下，在REST API中交换的消息未在架构文档中正式定义。相反，它们记录在html页面中，然后公司提供API测试页面，在那里他们可以看到示例请求和响应。这是记录API的一种非常实用的方式。有关此示例，请参阅https://api.stackexchange.com/docs/answers。

b）为了区分请求和响应，我想你会在XSD中使用不同的元素类型。也许我不理解这个问题。

c）如果请求是错误的内容类型，不包含XML文档，或者XML文档不符合所需的模式，则返回400是完全合理的。如果确实返回了400，那么最好还返回一个消息体，并提供一个XML文档，以提供更多信息：

<response> 
  <error>
    <code>101.4.c</code>
    <description>your request did not include an XML document</description>
    <link>http://example.com/errorinfo?code=101.4.c</link> 
  </error>
</response>

有关REST API设计的更多信息，请参阅http://dinochiesa.net/?p=192

RESTful Web服务：为同一资源记录XML

1 个答案: