RESTful Web服務：記錄同一資源的XML

Question

我正在使用W3C XML架構（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來構建應用程序，還是僅在服務器（接收）端使用它來驗證請求的出現？

在許多情況下，在架構api中沒有正式定義在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