是否（Un）-REST-full在返回集合時返回詳細信息？

Question

我的問題是關於設計一個獲取集合中項目列表的端點。這裏我的理解是，集合上的GET返回該集合中的項目列表，但沒有關於這些的詳細信息。

資源ID列表對於人類來說不是很好，因此GUI前端會請求集合中每個項目的詳細信息。

如果集合是說，「用戶」，然後對收集的得到的只是返回一個用戶ID列表（所有的人！分頁，我能想象嗎？）

的GUI然後請求細節每一個ID和使用它來填充接口。作爲一個例子，你可能會說，在這個界面中只顯示用戶的全名和電子郵件地址，允許用戶選擇一個來查看更多詳細信息。

現在，我認爲如果「列表檢索」返回的不僅僅是ID，還可能包括ID，全名和電子郵件地址，它會在客戶端和API之間節省很多後退和轉發每一個項目。

這是否會破壞RESTful-ness？你在哪裏停止了在單個請求中返回多少細節？你是否允許客戶端指定哪些屬性作爲請求的一部分？

怎麼樣「搜索」一個集合？您是否允許在GET上針對集合指定參數以「過濾」結果？

Answer 1

API的存在是爲了滿足客戶的需求。如果你的客戶需要這些細節，你應該返回它們。

也就是說，對於高度緩存的項目有一個權衡。如果列表不是靜態的，但內容是，您可能會更好地返回鏈接列表。然後客戶端爲每個元素進行一次調用，並且他們坐在緩存中。後來，通過中間緩存來調用這些元素，無論是在客戶端還是客戶端和服務器之間。這會以最初的絕對呼叫數量爲代價來減少呼叫列表的總帶寬。

另一種選擇是支持查詢參數，如?include=id, full-name, email。默認情況下，只需返回自我鏈接，但客戶端可以指定他們想要在他們回來的表示中填充的屬性。如果你支持這個查詢參數，我會建議默認只返回最重要的信息。

就搜索集合而言，它取決於搜索的性質和複雜性。查詢參數是一個選項。將POST用於搜索終結點並在正文中發送搜索條件也是合理的，特別是如果您的網址可能超過2k個字符（某些瀏覽器的默認網址長度限制）。您也可以按照這種方式進行保存的搜索 - 讓POST在服務器上創建搜索條件資源，並讓客戶端GET /widgets?search-criteria=<id>。