在RESTful CRUD API中處理ID

Question

我正在設計一個Create / Read / Update / Delete公共Web API端點，在JSON上使用基於HTTP的RESTful模式和JSON負載，並且想知道一個設計問題必須非常普遍，但是我卻很難找到指導。

讓我們僅關注API的“讀取”和“更新”部分。 當涉及到處理ID時，我對當前的“適當的” REST最佳實踐感到有些困惑。 這就是我的意思：

通過HTTP GET“讀取”員工將返回一個或多個“小部件” JSON對象（例如，我有一種方法來檢索滿足特定條件的所有小部件）。 每個窗口小部件對象都有一個ID字段，它是一個GUID。

我看到“更新小部件”端點的幾個設計選項：

1. HTTP PUT到整個小部件對象的/ api / widgets / {widget-id}。 如果存在對象中的“ ID”字段，則API將失敗 。 （我不喜歡這種方法，因為未經修改，無法將來自“讀取”端點的數據往返到“更新”端點）
2. HTTP PUT到整個小部件對象的/ api / widgets / {widget-id}。 如果存在，API將忽略對象中的“ ID”字段。 （我認為它比上述方法要好，但是提供的ID可能不正確，並且我認為靜默忽略不良數據是錯誤的）
3. HTTP PUT到整個小部件對象的/ api / widgets / {widget-id}。 API將驗證對象中的ID字段必須與 URI 中的ID 匹配 ，否則將失敗。 （我認為這甚至更好，但是數據仍然在URI和消息正文之間重復）
4. HTTP PUT到整個小部件對象的/ api / widgets / {widget-id}。 API將驗證對象中的ID字段必須不存在或必須與 URI 中的ID 匹配 ，否則將失敗。 （這是我傾向於的方法）
5. HTTP PUT到整個窗口小部件對象的/ api / widgets ，包括ID字段-即要更新的對象的ID將來自消息正文而不是URI。
6. 與＃5相同，但具有HTTP POST-如果指定了ID，則可能具有“ Update”語義，如果未指定，則可能具有“ Create”語義。

我可以在這里看到各種折衷。 選項6對我來說似乎特別優雅，但對“ RESTful”而言卻不是特別好，對於API用戶來說可能是一個陌生的模式。 我見過的大多數API設計指南文檔似乎都建議使用“ PUT到/ api / widgets / {widget-id}”方法，但對上面＃1/2/3/4的區別卻保持沉默。

那么“ REST完全正確” /最佳實踐方法是什么？ （對於使用我的公共API終結點的開發人員來說，這是最熟悉且最不會混淆的事情）。 還有我在這里沒有想到的其他設計選項（或設計注意事項）嗎？

Answer 1

如果絕對必須提供ID，則可以將其公開。 另一種方法是，您可以在實體中具有唯一字段。 在不傳遞ID的情況下，您也可以創建一個包含唯一字段的DTO。 在您的情況下，{widget-id}是唯一的，並且該ID始終是自動生成的int的ID。 使用POST，這是您使用公共API的最佳方法。

如果需要對窗口小部件進行多個操作，請使用“窗口小部件”（示例：site.com/widget）創建4個不同的端點，這些端點定義了get，post，put和delete作為不同的方法。 這意味着單個API會根據調用它的不同方法而有不同的功能。