REST API 設計 - 單個通用端點或多個特定端點

Question

這是一個比較主觀的問題，但我還是想聽聽別人的意見

我正在設計一個可由內部系統（最多幾個客戶端應用程序）訪問的 REST Api。

一般來說，API 需要更新不同汽車品牌的參數。 每個汽車品牌都有大約 20 個屬性，其中一些屬性在所有汽車品牌之間共享，有些是針對每個品牌的。

我想知道設計此 API 端點的更好方法是什么。

所以在第一種方法中，我有一個端點，它有一個字符串參數，我希望它是一個具有所有必要值的 JSON

PUT /api/v1/carBrands/

而在第二種情況的第二種方法中，我為每種類型的汽車品牌都有一個端點，每個端點都有一個類型化的 dto 對象，表示它需要的所有值。

PUT /api/v1/carBrand/1
PUT /api/v1/carBrand/2
.
.
.
PUT /api/v1/carBrand/n

第一種方法似乎節省了很多重復的代碼——畢竟唯一的區別是參數集。 但是，由於這接受任意字符串，最終用戶無法知道他應該通過什么 - 他需要有人告訴他和/或從文檔中閱讀。

第二種方法更具可讀性，任何人都可以填寫數據，因為他們知道它是什么。 但它主要涉及復制大約 20 次相同的代碼。

我真的很難選擇一個選項，因為這兩種方法都有其缺點。 我應該如何判斷什么是更好的選擇

Answer 1

我想知道設計此 API 端點的更好方法是什么。

根據您的示例，您似乎在詢問資源設計，尤其是您應該使用一種大型資源還是一系列較小的資源。

REST 沒有回答這個問題……無論如何也不是直接回答。 REST 所做的是確定緩存粒度在資源級別。 如果有兩條信息，並且您希望一條信息的無效也使另一條無效，那么這些信息應該是同一資源的一部分，也就是說，應該使用相同的 URI 訪問它們。

如果這不是您想要的，那么您可能應該傾向於使用分離的資源。

我不一定期望對Ford進行編輯會迫使我的本地Ferrari副本失效，因此這表明我可能希望將它們視為兩個不同的資源，而不是兩個子資源。

相比

/api/v1/carBrands#Ford
/api/v1/carBrands#Ferrari

和

/api/v1/carBrands/Ford
/api/v1/carBrands/Ferrari

在前一種情況下，我的緩存中有一個資源 (/api/v1/carBrands)； 我對它所做的任何更改都會使整個資源無效。 在后一種情況下，我緩存了兩個資源； 改變一個忽略另一個。

使用其中之一並沒有錯； 兩者都很好，並且有很多歷史。 他們進行了不同的權衡，其中一個可能更適合您今天要解決的問題。