REST API：使用內容類型與自定義參數或端點

Question

我正在為資源設計一個列表終結點，該終結點同時具有資源的完整版本和輕量版本，稱為/ transactions。 默認情況下，響應將包括完整的資源，但是還需要為客戶端提供資源列表的“簡化”版本。

第一種選擇是使用自定義參數（例如/ transactions？summary = true），第二種選擇是使用自定義端點，盡管不是非常RESTful（例如/ transactions / summary）

第三種選擇是使用content-type來允許客戶端聲明替代響應主體格式。 看起來如何？ （應用程序/ json +摘要）？ 有什么好的例子嗎？

還有其他選擇嗎？

Answer 1

使用Accept / Content-Type標頭的第三個選項允許媒體類型作為數據的表示形式，與數據本身分開。

GitHub的API是一個很好的例子： https : //developer.github.com/v3/media/

它使用http標頭允許客戶端選擇數據格式以及版本。 因此，在您的情況下，請求可能類似於：

curl http://api.host.com/transactions -H "Accept: application/summary+json"

並且響應將包含簡化數據格式的主體，並將Content-Type標頭設置為application/summary+json

如果您想對此進行更深入的研究，還可以使用供應商媒體類型作為application/vnd.yourcompany.summary+json 。 在這種情況下， vnd表示媒體類型是通常與特定於應用程序的媒體類型相關聯的供應商 。

更多信息：

• 集合+ JSON
• 類似的答案
• 寧靜的API設計