如何在 WebApi Core 中設計多個補丁請求

Question

我想知道在 WebApi .Net Core 中設計多個資源更新的最佳方法是什么。

例如，我想為users資源啟用以下功能

• 更新用戶密碼
• 更新用戶角色
• 更新用戶詳細信息（例如名字、姓氏等）

所以，根據 REST 教程和文章，我了解到我需要使用PATCH方法來更新部分資源。

我們在團隊中進行了一些討論，我們對這兩個選項感到困惑：

選項1

為不同的動作實現多個 PATCH 路由

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

選項 2

對整個資源實施 ONLY 單個 PATCH 操作。 用戶將發送 application/json-patch+json 進行部分更新。

• PATCH /api/users/id （接受JsonPatchDocument參數）

我試圖找到 Restful Route Namings 的最佳實踐，其中大部分僅涵蓋簡單的 CRUD 活動或嵌套資源。

對於這種多個 UPDATE 操作，我可以知道命名路由的最佳做法是什么嗎？ 或者它的深入研究的術語？ 謝謝。

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 之外。 使用 HTTP 請求方法GET 、 POST 、 PUT/PATCH 、 DELETE和兩個基本 URL 進行 CRUD 操作。 關鍵是開發人員可能不需要文檔來了解 API 的行為方式。否則，您將擁有一長串 URL 並且沒有一致的模式，這使開發人員難以學習如何使用您的 API

• 復雜的東西需要隱藏在背后? . 幾乎每個 API 都有許多參數，您可以以任何其他方式讀取、更新、過濾和使用它們。 但是所有這些參數都不應該在基地址中可見。 最好在對基地址的引用中指定參數。

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

另見鏈接

• Microsoft REST API 指南
• Zalando RESTful API
• 網頁 API 設計

Answer 2

將 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;