在 REST API 中使用 PUT 进行更新时是否应该允许发送完整的结构？

Question

我正在设计一个 REST API，我想知道处理资源更新的推荐方法是什么。更具体地说，我允许通过资源上的 PUT 进行更新，但是我应该在 PUT 请求正文中允许什么？

1. 总是资源的完整结构？
2. 总是资源结构的子部分（已更改）？
3. 两者的结合？

例如，以资源 http://example.org/api/v1/dogs/packs/p1 为例。 此资源上的 GET 将给出以下内容：

Request:
GET http://example.org/api/v1/dogs/packs/p1
Accept: application/xml

Response:
<pack>
  <owner>David</owner>
  <dogs>
    <dog>
      <name>Woofer</name>
      <breed>Basset Hound</breed>
    </dog>
    <dog>
      <name>Mr. Bones</name>
      <breed>Basset Hound</breed>
    </dog>
  </dogs>
</pack>

假设我想向包中添加一只狗（嗅探巴吉度猎犬），我会支持以下其中之一：

Request:
PUT http://example.org/api/v1/dogs/packs/p1
<dog>
  <name>Sniffers</name>
  <breed>Basset Hound</breed>
</dog>

Response:
HTTP/1.1 200 OK

还是

Request:
PUT http://example.org/api/v1/dogs/packs/p1
<pack>
  <owner>David</owner>
  <dogs>
    <dog>
      <name>Woofer</name>
      <breed>Basset Hound</breed>
    </dog>
    <dog>
      <name>Mr. Bones</name>
      <breed>Basset Hound</breed>
    </dog>
    <dog>
      <name>Sniffers</name>
      <breed>Basset Hound</breed>
    </dog>
  </dogs>
</pack>

Response:
HTTP/1.1 200 OK

两者都支持？如果建议通过结构的子部分支持更新，我将如何处理删除（例如当狗死亡时）？通过查询参数？

Answer 1

是的，始终发送资源的完整表示。否则，您将（根据 PUT 的常见定义和用法）仅用这只狗替换该包。

但是，您可能需要考虑以下事项：

• 使用 XML 命名空间或其他版本控制方法（例如？version=2） 在 URL 路径之外
• 将要添加的狗 POST 到 /dogs/packs/ p1。根据定义，POST 创建一个从属资源，以便将狗添加到资源包中。
• 稍微刷新一下你的网址。在我看来，你确实想要 /dogs/1234、/dogs/1235 等等，然后是 /packs/p1、/packs/p2。然后您也可以简单地将 发布到包中。

请记住，REST 要求您正确识别资源。包实际上并不是狗的从属资源，每只狗都应该有某种唯一的标识符。然后，当访问 /packs/p1/1234 时，您可能希望重定向到 /dogs/1234。或者，您也可以不使该 URL 可用，尽管接受将从属资源发布到相应包。

我想得越多，POST 方法就越有意义。也许您甚至可以为所有狗提供一个 /packs/p1/dogs/ 资源，与包分开。然后，您可以将所有者信息等内容放入 /packs/p1，通过 /packs/p1/dogs/ 获取所有狗的列表（其中应包含每只狗的 URL 列表） pack，例如 /packs/p1/dogs/1234，请参阅 HATEOAS），添加一条新狗到通过 POST 到 /packs/p1/dogs/ 来删除狗，并通过 DELETE /packs/p1/dogs/1235 来删除狗。每只狗都可以是完整的表示，甚至可以重定向到 /dogs/1234 等，也可以是该包上下文中狗的不同表示，但同样带有指向“完整”狗的链接。取决于您想要如何表示包中的单只狗，这当然也会影响您实际发布到 /packs/p1/dogs/ 的内容。 Full Dog 感觉不对，实际上应该只是一个 ID，如我上面所示，也许还有与包的关系有关的附加数据。

Answer 2

PUT 的作用是“替换”。所以，是的，您需要通过 PUT 请求提供完整的表示。

如果您只想更新资源的一部分，您有以下选择：

• 定义代表资源的资源
  部分并放置在那里
• 使用 POST 到子资源并有
  服务器返回 303 See Other with
  指向的 Location 标头
  主要资源
• 使用 PATCH

在您的情况下，最好将狗作为子资源（包中狗的集合）并以通常的 POST-as-append 方式 POST 到该子资源