用於創建資源的REST API修補程序方法

Question

使用JSONAPI 1.0標准設計API，沒有PUT方法。 只有POST方法可以創建資源，而PATCH可以部分更新。 我們有一個用例，用戶可以將請求發送到服務器，如果資源不存在，則必須創建該資源，否則進行更新。 RFC將這種方法描述為PUT。 接下來引用提到的針對PATCH的RFC 5789標准有信息：

“如果Request-URI沒有指向現有資源，則服務器可以根據補丁文檔類型（是否可以邏輯上修改空資源）和權限等來創建新資源。”

使用PATCH方法更新和創建資源是一個好主意嗎？ 應該使用哪種標准來支持PUT和PATCH方法（可能是OpenApi）？

如何解釋RFC描述？

最好的祝福

Answer 1

根據Postel's law您應該對自己的工作Postel's law be conservative in what you do, be liberal in what you accept from others Postel's law 。

PATCH使用的兩種常見媒體類型是application/json-patch+json （又名JSON補丁）和application/json-merge-patch+json （又名MergePatch）。

MergePatch定義了兩個規則，這些規則確定是否需要添加，刪除或更新零件。 規范定義，需要通過調用帶有兩個參數 （目標資源和接收的表示形式）的函數來處理該類型的請求。 目標本身可能是JSON值或未定義。 如果該資源尚不存在，則該資源是不確定的，並且將導致收到的補丁文檔中的所有值都添加到該尚未定義的資源中。 這基本上就是您的資源創建。

與MergePatch相比，JSON Patch被指定為僅在JSON文檔上運行。 沒有提到在沒有可用資源的情況下如何應用補丁。 如果您查看提供的操作，則從某種意義上講是有意義的，例如test ， remove ， replace或move僅在原始JSON文檔中存在對應項時才有效。 這種媒體類型與實際的PATCH定義非常接近，因為客戶端會發送一組指令，這些指令是由客戶端先前計算的，需要由服務器自動應用。 所有更改或全部都不應用。 在這里，客戶端應該已經預先獲取了目標資源的當前狀態，否則客戶端將無法計算必要的更改以將當前表示轉換為所需的表示。 因此，僅當已經有可用資源時，才應用該媒體類型的表示形式才有意義。 如果客戶端看到尚無目標資源可用，則可以簡單地使用POST然后創建資源。 如果客戶端發送的補丁文件僅包含add操作，我將創建一個JSON表示形式，並相應地添加所有字段。

如您所見，如何在HTTP中完成PATCHing有兩種不同的方法。 一個非常接近數十年來如何在軟件工程中完成補丁的最初想法，而另一種方法則是對部分更新遠程資源的一種更為實用的方法。 您選擇使用還是支持哪一個（最好兩種情況都可以）。

Answer 2

我們有一個用例，用戶可以將請求發送到服務器，如果資源不存在，則必須創建該資源，否則進行更新。

正確的答案，在這種情況下，幾乎可以肯定將是POST請求發往收集資源，並讓服務器弄清楚“正確”的事情。

可以通過向表示資源集合的URL發送POST請求來創建資源。

使用PUT創建資源時，假定客戶端可以/應該猜出新資源的正確標識符應該是什么。 如果我們沒有給客戶端該權限/控制權，則請求需要改為使用穩定的target-uri，然后服務器計算對其他資源的副作用。

在JSON：API中，服務器可以控制新項目的URI選擇。

POST /photos HTTP/1.1
Content-Type: application/vnd.api+json

...

HTTP/1.1 201 Created
Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000

如果API支持PUT語義，則等效的更改將類似於

PUT /photos/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Content-Type: application/vnd.api+json

HTTP/1.1 201 Created

但是JSON：API決定PUT還不有趣 。 在這兩行之間的閱讀中，作者決定應保留PUT直到更多實現證明他們理解HTTP規范為止。

因此，您可以使用POST到集合進行創建，並使用PATCH對該項目進行部分或完全替換。

反過來，這意味着如果客戶端不/不知道資源已經存在，則應將其發布到集合中。 反過來，服務器應意識到該資源可能已經存在，並且做了一些明智的事情（替換資源的表示形式，將客戶端重定向到該資源等）。 服務器如何實現的將是實現細節。

在研究Internet與REST HTTP方法的關系時，我從未見過PATCH可用於資源創建，因此，我對JsonApi放棄PUT方法感到驚訝。

PATCH當然可以用於資源創建-請參閱RFC 5789

如果Request-URI沒有指向現有資源，則服務器可以根據補丁文檔類型（是否可以邏輯上修改空資源）和許可權等來創建新資源。

這是一個不常見的選擇，因為PUT語義更適合該用例。 選擇支持PATCH而不支持PUT是很奇怪的。

我對JsonApi放棄PUT方法感到驚訝

我也很驚訝。

通過注冊新的個人資料 ，鼓勵社區為您所需的語義采用通用模式，可能會解決您的問題。