用于从子资源列表中更新/添加/删除项目的 REST 设计

Question

我想知道当您拥有包含子资源列表的资源时哪个是最佳实践。例如，您有资源作者，其中包含姓名、身份证、生日和书籍列表等信息。此书单仅与作者有关​​。因此，您有以下情况:

您想在书单中添加一本新书

您想更新列表中的一本书的名称

您想从列表中删除一本书

解决方案 1

我搜索了哪个是正确的设计，我发现了多种方法。我想知道是否有一种标准的设计方法。我认为书上的设计说有以下方法:

添加:POST /authors/{authorId}/book/

更新:PUT /authors/{authorId}/book/{bookId}

删除:DELETE /authors/{authorId}/book/{bookId}

解决方案 2

我的解决方案是只有一个 PUT 方法可以完成所有这 3 件事，因为书籍列表仅存在于对象作者内部，而您实际上是在更新作者。就像是:
PUT /authors/{authorId}/updateBookList (并在作者对象内发送整个更新的书单)

我在我的场景中发现了多个错误。例如，从客户端发送更多数据，在客户端有一些逻辑，在 API 上进行更多验证，并且还依赖于客户端拥有最新版本的 Book List。

我的问题是:这样做是反模式吗？

情况 1. 在我的情况下，我的 API 使用的是另一个 API，而不是数据库。使用的 API 只有一种“updateBookList”方法，所以我猜想在我的 API 中复制这种行为也更容易。也是正确的吗？

情况 2. 但是，假设我的 API 将使用数据库，是否更适合使用解决方案 1？

另外，如果你能提供一些文章、书籍，你可以在其中找到类似的信息。我知道这种设计不是一成不变的，但一些指导方针会有所帮助。 (示例:来自 Book REST API Design Rulebook - Masse - O'Reilly)

Answer 1

解决方案 2 听起来很像老式 RPC，其中调用了一个执行某些处理的方法。这就像 REST 反模式，因为 REST 的重点是资源而不是方法。您可以对资源执行的操作由底层协议(protocol)(在您的情况下为 HTTP)给出，因此 REST 应该遵守底层协议(protocol)的语义(它的少数约束之一)。
此外，REST 并不关心您如何设置 URI，因此实际上没有 RESTful URL。对于自动化系统，遵循特定结构的 URI 与充当 URI 的随机生成的字符串具有相同的语义。尽管应用程序应该使用 rel，但我们人类将意义放入字符串中。属性，它为 URI 提供了应用程序可以使用的某种逻辑名称。期望 URL 具有特定逻辑组合的应用程序已经与 API 紧密耦合，因此违反了 REST 试图解决的原则，即客户端与服务器 API 的解耦。
如果您想以 RESTful 方式通过 PUT 更新(子)资源，则必须遵循 put 的语义，该语义基本上表明接收到的有效负载替换了更新前在给定 URI 处可访问的有效负载。

The PUT method requests that the state of the target resource becreated or replaced with the state defined by the representationenclosed in the request message payload.

...

The target resource in a POST request is intended to handle theenclosed representation according to the resource's own semantics,whereas the enclosed representation in a PUT request is defined asreplacing the state of the target resource. Hence, the intent of PUTis idempotent and visible to intermediaries, even though the exacteffect is only known by the origin server.

关于部分更新 RFC 7231声明可以使用 PATCH 进行部分更新正如@Alexandru 建议的那样或发出 PUT直接向子资源请求，其中有效负载将子资源的内容替换为有效负载中的内容。对于包含子资源的资源，这具有部分更新的影响。

Partial content updates are possible bytargeting a separately identified resource with state that overlaps aportion of the larger resource, or by using a different method thathas been specifically defined for partial updates (for example, thePATCH method defined in [RFC5789]).

因此，在您的情况下，您可以通过 PUT 直接发送更新的图书收藏。操作类似于 .../author/{authorId}/books替换旧集合的资源。因为这可能不适用于撰写过许多出版物的作者 PATCH可能是更可取的。但是请注意， PATCH需要原子和事务行为。要么所有 Action 都成功，要么都不成功。如果在操作中间发生错误，您必须恢复所有已执行的步骤。
关于您对进一步文献的要求，SO 不是问这个问题的正确地方，因为这有一个自己的离题关闭/标记原因。