1

我正在使用 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 内容。

提前致谢

4

1 回答 1

0

a) 创建一个 XSD 并在该 XSD 中定义多种类型是可以的。在单个 XSD 中定义请求/响应对对我来说似乎是合理的。请记住 XSD 的消费者或用户。会是谁？您是否希望您的 API 的用户使用该 XSD 来构建应用程序，还是仅由服务器（接收）端使用它来验证传入的请求？

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

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

c) 返回 400 是完全合理的，如果请求是错误的内容类型，不包括 XML 文档，或者 XML 文档不符合所需的模式。如果您确实返回了 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

于 2012-06-30T02:40:00.713 回答