如何設計REST API以允許返回帶有元數據的文件

Question

假設我正在設計一個REST API，我需要客戶端能夠獲取帶元數據的文件。 設計資源/運營的好方法是什么？

我想到了一些想法：

• 單個資源（即GET / files / {fileId}），它返回包含文件和帶元數據的JSON / XML結構的多部分響應。 我覺得這不是一個很好的方法。 例如，您不能使用客戶端的Accept標頭來確定他們是否需要XML或JSON元數據表示，因為響應類型在兩種情況下都是多部分的。

• 兩個資源（即GET / files / {fileId}和GET / files / {fileId} / metadata），其中第一個返回文件本身，第二個是帶有元數據的JSON / XML結構。 可以存在從元數據到文件的鏈接。 但是，如何將文件鏈接與文件一起發送？

Answer 1

我建議使用你提出的第二個想法。 這是大多數主要網絡驅動器（Box，Dropbox，Google Drive等）使用的策略。 它們通常具有明顯不同的URL，因為它們將內容和元數據存儲在不同的位置。

您可以使用指向元數據的鏈接向文件響應添加鏈接標頭。 RFC 5988中描述了鏈接頭。 當前注冊的鏈接關系集合在這里 。 關閉袖口，似乎所describedBy關系在這里是合適的。

Answer 2

我在以下API設計方面取得了成功。 這與您建議的略有不同，主要資源只包含指向其組件的鏈接。

POST /file
Request
  <bytes of file>
Response
  Location: /file/17
  {
    "id": 17
  }

GET /file/17
  {
    "data": "/file/data/17",
    "metadata": "/file/metadata/17"
  }

GET /file/data/17
  <bytes of file>

GET /file/metadata/17
  {
    "type": "image",
    "format": "png"
  }

DELETE /file/17

Answer 3

您的第一個選項根本不是一個好的選擇，因為它違反了以下REST約束。

通過 統一接口原則下的這些表示來操縱資源 。

當客戶端持有資源的表示（包括附加的任何元數據）時 ，它具有足夠的信息來修改或刪除資源。

如果你剎車的話。 您的網址不會被視為RESTful。

關於它的Wiki 。