如何设计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 。