如何在 WebApi Core 中设计多个修补程序请求

Question

我想知道在WebApi .Net Core中设计对资源的多个更新的最佳方法是什么。

例如，我想为users资源启用以下功能

• 更新用户密码
• 更新用户角色
• 更新用户详细信息(例如名字、姓氏等)

因此，根据 REST 教程和文章，我了解到我需要使用PATCH方法来更新部分资源。

我们在团队中进行了一些讨论，我们对以下两个选项感到困惑：

选项 1

为不同的操作实现多个 PATCH 路由

• 补丁/api/users/{id}/password
• 补丁/api/users/{id}/role
• 补丁/api/users/{id}/details

选项 2

仅对整个资源实施单个 PATCH 操作。 用户将发送application/json-patch+json进行部分更新。

• 补丁/api/users/id(接受JsonPatchDocument参数)

我试图找到 Restful 路由命名的最佳实践，其中大多数只涵盖简单的 CRUD 活动或嵌套资源。

对于这种多次更新操作，我可以知道命名路由的最佳实践是什么吗？ 还是深入研究的术语？ 谢谢。

Answer 1

PATCH请求用于更新单个资源的一部分，即只应替换资源字段的特定子集。语义最好描述为"请根据我的更改请求更改 URL 标识的资源"。

• PATCH请求通常应用于单个资源，因为修补整个集合具有挑战性
• PATCH请求通常对不存在的资源实例不可靠
• 在成功的PATCH请求中，服务器将更新由有效负载中的更改请求定义的 URL 寻址的部分资源
• 成功的PATCH请求通常会生成200或204(如果资源已更新，返回或不返回更新的内容)

注意：由于正确实现PATCH有点棘手，因此我强烈建议为每个端点选择以下模式之一。按优先顺序：

1. 使用带有完整对象的PUT以尽可能长地更新资源(即根本不使用PATCH)。
2. 尽可能将PATCH与部分对象一起使用，以便仅更新资源的一部分。(这基本上是 JSON 合并修补程序，这是一种专门的媒体类型application/merge-patch+json，是部分资源表示形式。
3. 将PATCH与 JSON 修补程序一起使用，JSON 修补程序是一种专用媒体类型application/json-patch+json，其中包含有关如何更改资源的说明。
4. 如果请求未以媒体类型语义定义的方式修改资源，请使用POST(对正在发生的事情进行正确描述)而不是PATCH。

选项 1的设计似乎很糟糕，因为每个属性都有很多终结点。

选项 2遵循 REST 建议，并在 RFC 6902 中指定

您可以通过以下方式实现它：

• Delta(Microsoft ASP.NET WebAPI OData的一部分)：使用JSON时，它在数字方面存在一些问题。您还需要安装软件包及其所有重要的依赖项;
• JSON 补丁：客户端必须组织每个操作的数据，并且请求的大小未优化。
• 使用Simple.HttpPatch，可以轻松应用部分更新
• 另一个 SimplePatch 实现

路线命名

• 资源名称使用复数名词。不要混淆单数和复数名词。保持简单，对所有资源只使用复数名词(users，而不是user)

• 如果每个资源有两个基本 URL，则第一个 URL 用于集合(列表);第二个 URL 用于集合中的特定元素(/users和/users/1)

• 如果您有关系，请为其使用子资源

/users/1/phones - 返回用户 1

另请参阅链接

• Microsoft REST API 指南
• Zalando RESTful API
• 网页接口设计