如何設計api以REST風格的非主鍵檢索一個資源？

Question

原來，我們有一個API GET /users/:id通過其主鍵檢索user。

現在我們需要一個新的API來檢索user的電子郵件。

GET /users?email=xx@xx.com似乎想要一個集合。

GET /users/byEmail/:email包括非名詞詞byEmail。

還有其他的選擇嗎？

Answer 1

您建議的兩種方法都是有效的，但我可能不會這樣做，因爲最好堅持每個資源使用一個 URI。要做到這一點的另一種常用方法是：

/users/id/:id 

或

/users/email/:email 

我應該指出的是，查詢參數VS網址參數或/name/:value VS /:value的選擇不是什麼使服務「REST風格」。換句話說，擁有「漂亮」或「可讀」的URL並不意味着你的服務是RESTful的。

REST的關鍵點之一是通過URI進行資源識別，即特定的URI將始終指向特定的資源。在電子郵件的情況下，這可能會改變（用戶可能想要更改他們的電子郵件地址），所以此URL不再隨時識別此用戶。

更RESTful方法是使明確的，這是一個真正的搜索而不是標識，並有一個URI是這樣的：

/search/users/email/:email 

這是更RESTful的，因爲這個URI總是標識相同的資源，即該電子郵件地址的搜索結果。請注意，這種情況下的資源是搜索結果，而不是用戶資源本身。

Answer 2

我喜歡在路徑末尾有/的URIs集合的約定。所以GET /users?email=xx@xx.com返回一個項目，GET /users/?email=xx@xx.com返回一個具有單個項目的集合。但是。你不必使用這個約定。

另一個選項是使用/users/:email，如果你能解決服務器，或/users-by-email/:email或/users/email-:email等的路由...你選擇哪個URI結構，只要您的REST API與HATEOAS constraint滿足這並不重要。