REST API 更新設計 Object 圖

Question

我正在設計一個 REST API 並正在尋找更新 object 圖的推薦最佳實踐。 我的問題在一個例子中得到了最好的解釋，所以假設我有一個 GET 資源，如下所示：

URI: /人/123

此 URI 返回一個 object 圖形，如下所示：

{
    "name":"Johnny",
    "country":{"id":100,"name":"Canada"},
    "likes":[
        {"id":5,"name":"Fruit"},
        {"id":100,"name":"Sports"}
    ]
}

當允許 API 消費者更新此資源時，您希望如何通過 PUT 或 PATCH 更新 object？ 更新“name”屬性非常簡單，但我不確定“country”或“likes”，因為消費者只能更改與其他對象的關系而不能創建新對象。

這是請求更新的一種方法：

{
    "name":"Bob",
    "countryId":200
    "likeIds":[3,10,22]
}

此更新會將資源更改為以下內容：

{
    "name":"Bob",
    "country":{"id":200,"name":"United States of America"},
    "likes":[
        {"id":3,"name":"Cars"},
        {"id":10,"name":"Planes"},
        {"id":22,"name":"Real Estate"}
    ]
}

這種設計明確而明確地要求消費者僅更新“人”的“ID”，但我擔心 PUT/PATCH 的 object 圖看起來與 GET 不同，使得 API 難以學習和記憶。 所以另一種選擇是請求 PUT/PATCH，如下所示：

{
    "name":"Bob",
    "country":{"id":100},
    "likes":[
        {"id":3},
        {"id":10},
        {"id":22}
    ]
}

這將產生與之前更新相同的變化，並且不會改變 object 圖。 但是，它並沒有讓 API 消費者清楚地知道只能更新“ID”。

在這種情況下，推薦使用哪種方法？

Answer 1

在我看來，您應該對 GET 和 PUT 請求保持相同的結構。 為什么？ 因為將 map JSON/XML 數據轉換為對象很常見，如果 JSON 模式始終相同，則大多數（如果不是全部）執行實際映射的軟件效果最好。

所以你的網絡服務應該接受以下 JSON 代碼：

{
    "name":"Joe",
    "country":{"id":200,"name":"United States of America"},
    "likes":[
        {"id":5,"name":"Fruit"}
    ]
}

但是，它不必考慮國家名稱，可能只關注國家 ID。