用於管理狀態的 RESTful API 端點

Question

我有一個 REST API 並想為某些資源實現不同的狀態。 API 處於 理查森成熟度 Model的第 2 級。

關於更改狀態的端點，我已經看到了很多不同的方法，但我不確定推薦的方法是什么。

我的場景如下：我的實體是訂單。 訂單可以打開、關閉和進行中。

1. 我可以使用請求正文向/orders/{id} PATCH請求

{
 "state": "in-progress"
}

2. 我可以將操作參數添加到端點/orders/{id}/status/in-progress並發出POST請求以觸發該操作。 但這會有 RPC 的味道。
3. 我可以將 state 視為資源並發出PUT請求來更新它。 /orders/{id}/state

{
  "state": "in-progress"
}

除此之外，我不確定響應正文中應該包含什么。

1. 響應只能是202 Accepted without body。
2. 或者以更新的 state 作為主體的200 Ok 。

{
  "state": "in-progress"
}

3. 或者200 Ok的訂單，它更新為 state 作為正文。

{
  "id": 1
  "state": "in-progress"
}

4. 或者訂單的200 Ok並且它已更新 state + 下一個可能的狀態為正文。 這感覺像是邁向超媒體/成熟度 3 級的一小步。

{
  "id": 1
  "state": "in-progress"
  "nextStates": ["closed"]
}

有很多機會。 似乎我不能 model 端點之類的資源，應該如何為 RESTful API 完成。 但我也不想使用 RPC 中的操作。 而且我知道如果你有超媒體，它只是 REST，但實現起來既復雜又昂貴。

Answer 1

基本思想：資源是文檔的抽象。 客戶端通過請求修改文檔將信息發送到服務器。 有用的業務活動是由對文檔的修改觸發的副作用。

因此，如果您的客戶端想要告訴服務器有關訂單的 state 的信息，那么想法是找到具有 state 信息的文檔，並發送一條消息請求修改該文檔。

在 web 上，我們通過提交 forms 來做到這一點 - 描述我們想要對文檔進行的更改的小消息。 這可能看起來像

POST /orders/12345
Content-Type: application/x-www-form-urlencoded

action=changeState&state=in-progress

另一種選擇是在本地編輯文檔，然后向服務器發送編輯后文檔的副本

PUT /orders/12345
Content-Type: application/json

{
    "id": "12345",
    "items": [
       "loaf of bread",
       "container of milk",
       "stick of butter"
    ],
    "state": "in-progress"
}

這里的架構與“GET /orders/12345”提供給我們的架構相同，我們將整個文檔發送回服務器，包括我們的更改。

當文檔非常大（相對於 HTTP 標頭）並且更改很小時，我們可能更願意發送描述更改的補丁文檔。 例如

PATH /orders/12345
Content-Type: application/json-patch+json

[ {"op":"replace", "path":"/state", "value":"in-progress"} ]

這與 PUT 的想法相同：我們對文檔副本進行了更改，並要求服務器更改其文檔副本以匹配我們的副本。

---

除此之外，我不確定響應正文中應該包含什么。

200 OK，任意一個

• 動作狀態的表示（又名成功消息）
• 資源的更新表示

元數據（特別是 Content-Location 標頭）告訴客戶端哪個是哪個。