如何在 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 进行部分更新。

• PATCH /api/users/id （接受JsonPatchDocument参数）

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

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

Answer 1

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

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

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

1. 只要可行，就使用PUT完整的对象来更新资源（即PATCH根本不使用）。
2. PATCH尽可能与部分对象一起使用以仅更新资源的部分内容。（这基本上是JSON Merge Patch，一种特殊的媒体类型application/merge-patch+json，是部分资源表示形式。）
3. PATCH与JSON Patch一起使用，这是一种特殊的媒体类型application/json-patch+json，其中包含有关如何更改资源的说明。
4. 如果请求未以媒体类型语义定义的方式修改资源，则使用POST（并对正在发生的情况进行正确描述）而不是。PATCH

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

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

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

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

路线命名

• 使用复数名词作为资源名称。不要混淆单数和复数名词。保持简单，所有资源仅使用复数名词（users, 而不是user）

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

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

/users/1/phones - 返回用户 1 的电话列表
/users/1/phones/1 - 返回用户 1 的电话 #1

• 将动词排除在基本 URL 之外。使用带有两个基本 URL 的 HTTP 请求方法、 、GET来POST进行CRUD 操作。关键是开发人员可能不需要文档来了解 API 的行为方式。否则，您将拥有一长串 URL 并且没有一致的模式，这使得开发人员很难学习如何使用您的 APIPUT/PATCHDELETE

• 复杂的事情需要隐藏在背后?。几乎每个 API 都有很多参数，您可以读取、更新、过滤并以任何其他方式使用它们。但所有这些参数在基地址中都不应该可见。最好在基地址的引用中指定参数。

GET /users/1234?firstName=Bill&PhoneNumber="1111"

另请参阅链接

• 微软 REST API 指南
• Zalando RESTful API
• 网页API设计