如何在超媒體 api 的更新請求中引用資源？

Question

我對 REST API 如何工作以及如何通過超媒體鏈接資源進行了一些研究。 大多數有關鏈接資源的示例都與服務器的響應有關。 但是我想知道當某個資源應該更新時如何引用其他資源。

讓我們以居住在特定位置的人的簡單資源為例：

/api/persons/alice
{
  "name": "Alice",
  "location": {
    "id": 1,
    "links": {
      "self": "/api/locations/1"
    }
  }
}

現在我想將該位置更新為另一個現有位置。 但是我該如何表示呢？ 我可以嗎：

1. 引用新位置的id

PUT /api/persons/alice
{
  "name": "Alice",
  "location": 2
}

2. 引用新位置的 URI

PUT /api/persons/alice
{
  "name": "Alice",
  "location": "/api/locations/2"
}

3. 還要別的嗎？

Answer 1

HTTP PUT 具有遠程創作語義 - 您應該將有效負載視為文檔的新表示，由一些通用 HTTP 感知文檔編輯器操作。

GET /api/persons/alice HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "Alice",
  "location": {
    "id": 1,
    "links": {
      "self": "/api/locations/1"
    }
  }
}

PUT /api/persons/alice HTTP/1.1
Content-Type: application/json

{
  "name": "Alice",
  "location": {
    "id": 2,
    "links": {
      "self": "/api/locations/2"
    }
  }
}

200 OK

這里的假設是你的 API 的消費者熟悉這里的模式，並且理解語義，哪些字段是可選的，哪些是必需的，等等。

（讓它在很長一段時間內工作意味着投入精力來設計你的模式，選擇合理的默認值，等等）。

請仔細遵守PUT 規范的這一部分：

源服務器應該驗證 PUT 表示是否與服務器對目標資源的任何約束一致，這些約束不能或不會被 PUT 更改......當 PUT 表示與目標資源不一致時，源服務器應該通過轉換表示或更改資源配置使它們保持一致......

...

源服務器不得在對 PUT 的成功響應中發送驗證器 header 字段（第 7.2 節），例如 ETag 或 Last-Modified 字段，除非請求的表示數據在未對正文應用任何轉換的情況下保存......

換句話說，服務器不需要“存儲”所提供的新表示。