REST API 设计 - PUT 请求的资源关系和幂等性：完整的资源表示究竟是什么意思？

Question

我了解，对于部分更新，必须采取非幂等的操作。为此，一种有效的方法是对该资源发出 POST 请求。

我有一个关于相关资源的问题。例如想象以下资源及其属性：

1. 帐户
   身份证
   名称
   帐号#
   用户（一个集合）

2. 用户
   身份证
   姓名

现在假设我想对帐户进行部分更新 - 例如，更改帐户的名称。

我可以提出以下请求作为有效的部分更新：

POST /account/id/123

{
    "name" : "My New Name"
}

我的问题是关于一个完整的 PUT 请求，它必须是幂等的并且必须包含资源的完整表示。

我可以将以下作为有效的幂等请求吗？

PUT /account/id/123

{
    "name" : "My New Name",
    "accountNumber" : "654-345-4323"
}

这是否被认为是有效的幂等操作？我已经包含了所有顶级“帐户”信息，但我质疑它，因为我没有发布属于该帐户的所有 USERS。

为了成为有效的幂等请求，我是否需要在 PUT 请求中也包含它的所有子资源？

Answer 1

如果您想将 PUT 请求设计为完整的资源替换，那么这意味着您还需要为资源的所有可分配（可编辑）属性分配值，包括资源的关系（链接）。否则，未设置的属性将被视为设置为null。

对于部分请求，您可以使用 PATCH HTTP 方法。如果您的资源表示足够简单，可以使用部分更新，那么还有一个 PUT 约定。

PATCH vs. PUT

引用：

PATCH 与 PUT

HTTP RFC 规定 PUT 必须采用完整的新资源 表示为请求实体。这意味着，例如，如果 只提供了某些属性，那些应该被删除（即设置 为空）。

最近提出了一种称为 PATCH 的附加方法。这 此调用的语义类似于 PUT，因为它更新资源，但 与 PUT 不同，它应用增量而不是替换整个 资源。在撰写本文时，PATCH 仍是一个提议的标准 等待最终批准。

对于简单的资源表示，差异往往不是 很重要，许多 API 只是将 PUT 实现为 PATCH 的同义词。 这通常不会带来任何问题，因为它不是很常见 您需要将属性设置为 null，如果需要，您可以 总是明确地包含它。

但是对于更复杂的表示，尤其是列表， 能够准确地表达变化变得非常重要 你想做。因此，我现在建议两者 提供 PATCH 和 PUT，并让 PATCH 做一个相对更新并拥有 PUT 替换整个资源。

重要的是要认识到 PATCH 的请求实体是 它正在修改的实体的不同内容类型。反而 作为一个完整的资源，它是一个描述 对资源进行的修改。对于 JSON 数据模型， 是这篇文章所提倡的，我相信有两个 定义补丁格式的明智方法。

1. 一种非正式的方法，您可以接受带有部分内容的 dict 对象的表示。只有存在的属性是 更新。不存在的属性将被单独保留。这种方法 很简单，但它的缺点是如果资源具有复杂的 内部结构包含一个大的字典列表，那么 需要在实体中给出整个字典列表。有效地修补 再次与 PUT 相似。
2. 更正式的方法是 接受修改列表。每个修改都可以是一个字典 指定要修改的节点的JSON路径，修改 （“添加”、“删除”、“更改”）和新值。

Answer 2

一个更容易理解的方法是考虑 PUT 方法忽略目标资源的当前状态，因此“完整资源表示”意味着它必须具有替换现有资源所需的所有数据新资源。

在您的示例中，这可能是没有用户的帐户的有效完整表示。

服务器可以在缺少某些内容时采用默认值，但应该正确记录这一点，因为某些用户可能会将其与部分更新混淆。