如何在 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

将 PUT 与 json 整个对象一起使用，只更改必要的内容

类似于（使用 try-catch ofc）

[HttpPut("UpdateUser/{id}")]
public bool UpdateUser(string/int id, [FromBody]UrObject value)
{
    var item = UrObjRepo.WHere(w=> w.Key == id).FirstOrDefault();
    if (item==null)
    {
        return false; //not found item to update
    }
    UrObject.someValue = value.newValue.hasValue ? value : UrObject.someValue;
    ...
    UrObjRepo.update(UrObject);
}

在那个 JSON 你不能拥有所有的属性..只是那些你想改变的...... 原因：

UrObject.someValue = value.newValue.hasValue ? value : UrObject.someValue;

Answer 2

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

PATCH 请求通常应用于单个资源，因为修补整个集合具有挑战性
PATCH 请求通常无法抵抗不存在的资源实例
在成功的 PATCH 请求中，服务器将更新由 URL 寻址的部分资源，如负载
成功的 PATCH 请求通常会生成 200 或 204（如果资源已更新，有或没有返回更新内容）

注意：由于正确实施PATCH有点棘手，我强烈建议根据endpoint.In偏好选择以下模式中的一种且仅一种订单：

对完整对象使用 PUT 以尽可能长时间地更新资源（即根本不使用 PATCH）。
对部分对象使用 PATCH 以尽可能只更新资源的一部分。（这基本上是 JSON Merge Patch，一种特殊的媒体类型 application/merge-patch+json，是部分资源表示。）
将 PATCH 与 JSON Patch 结合使用，这是一种专门的媒体类型 application/json-patch+json，其中包含有关如何更改资源的说明。
如果请求没有以媒体类型语义定义的方式修改资源，则使用 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 - returns a list of phones for user 1
/users/1/phones/1 - returns phone #1 for user 1

让动词远离你的基础 URLs。使用 HTTP 请求方法 GET、POST、PUT/PATCH、DELETE 和两个基础 URLs 进行 CRUD 操作。关键是开发人员可能不需要文档来理解 API behaves.In 其他方式，您将拥有一长串 URL 并且没有一致的模式使开发人员很难了解如何使用您的 API
复杂的东西需要隐藏在?的背后。几乎每个 API 都有很多参数，您可以读取、更新、过滤并以任何其他方式使用它们。但是所有这些参数都不应该在基地址中可见。参数内最好指定对基地址的引用。

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

另见链接

如何在 WebApi Core 中设计多个补丁请求

How to design Multiple Patch requests in WebApi Core

rest

patch

asp.net-core-webapi