API的URL設計

Question

我正在爲我們的後端使用私人API。
我有擁有關聯的集合。
每個集合都可以請求分頁，也可以請求關聯並對這些關聯進行分頁。

我們不知道要使用哪個URL設計......我們正在考慮：

• /users.json?per_page=10 &協會=零件，試鏡& parts_per_page = 5 & auditions_per_page = 5

• /users.json?per_page=10 &關聯[] =份&關聯[] =試鏡& parts_per_page = 5 & auditions_per_page = 10

• /users.json?per_page=10 &協會[試聽] =真&協會[零件] [per_page] = 5

你覺得呢？你會選哪一個？爲什麼？這是不是看起來像有效的網址計劃之一？

謝謝！

Answer 1

我的回答：/users.json。 HTTP針對大粒度超媒體傳輸進行了優化;緩存是其中的重要組成部分，上面給出的任何URI方案都非常緩存友好。

例如，Squid是一個流行的HTTP緩存，默認情況下，它不會緩存任何具有查詢字符串的URL。另外，許多客戶端甚至服務器和中介都以未定義的順序生成和使用查詢字符串參數;也就是說，「a = 3 & b = 5」可以任意改寫爲「αb = 5 & a = 3」。但是，對於HTTP緩存，順序很重要，即使它們具有相同的內容，這兩個頁面也會分開緩存。當你添加參數時，這個問題呈指數增長。

您應通過兩個設計你的資源（和他們交涉），以充分利用高速緩存的對立而是相輔相成的技術：

1. 組合分散，部分表示成更大的，統一表示，和
2. 獨立的大，沿着緩存邊界（往往是事務性邊界）統一表示爲較小的表示，但通過超鏈接相關。

對於您的情況，第1步意味着將關聯和零件組合成「用戶」表示形式，沒有任何客戶端配置哪些和多少個選項的選項。這將允許您積極地緩存單個響應表示，而不會由於所有查詢字符串選項而使您的（及其緩存）重載組合式爆炸式響應。

步驟2意味着將/users.json分隔成單獨的「用戶」實體，每個實體都具有「關聯」資源和「部件」資源。所以/users/{id}和/users/{id}/associations和/users/{id}/parts。然後「/ users」資源返回一個超鏈接數組到每個「/ users/{id}」資源，並且每個「/ users/{id}」表示包含到其關聯和部分的超鏈接（該部分更具可塑性 - - 它可能會更好地將您的應用程序嵌入到用戶資源中直接嵌入到用戶資源中），這將允許您積極緩存每個「需求」資源的響應，而不必緩存整個數據庫。用戶會尖叫「但是這是網絡流量的10倍！」對此你冷靜地迴應，「不，這是網絡流量的1/10，因爲10次請求的資源中有9次已經位於客戶端（瀏覽器）緩存（當它們不存在時，它是服務器計算資源的十分之一，因爲它們坐在服務器端緩存中，並且當它們不在那裏時，我們避免了令人討厭的機智h服務器上的智能緩存）。「

當然，如果/users資源是每天新增訪問者數百萬，那麼您的優化路徑可能會有所不同。但它似乎不是基於您的示例URI方案。

Answer 2

restful-url標籤下有很多有用的帖子。

一些有用的帖子：

Do REST API URLs have to look like this?

Best practices on using URIs as parameter value in REST calls.

How to create REST URL's without verbs?

Answer 3

我會去的第一個1。我不喜歡在URL上看到[]符號，恕我直言，它使客戶更難以使用和理解。建議的一些變化。

1）作爲聯想似乎是一個數組，變更爲協會（複數，如果我是正確的，它是一個數組）

2）您也可以嘗試把默認per_page和一個可選的一個，甚至是聚合，就像per_page_parts_auditions，而不是同時使用per_page_parts和per_page_auditions。我不會這樣做，如果你的API被設計爲公開的，因爲它更容易使用但更難理解，但是因爲你發佈它是私有的。應該是避免複製的好方法。