具有多個必需參數的RESTful URI的最佳設計是什么？

Question

我想看看是否有更多經驗豐富的Web服務資深人士可以評論在我需要強制參數的地方設計RESTful URI的最佳方法。 舉個例子，我想設計一個請求數據的URI：

example.com/request/distribution

但是，根據我的理解，方法是更多數據應該返回更高級別，而如果應用更具體的URI關鍵字將返回更詳細的數據，但在我的情況下，我需要至少3個值才能實現。 這3個值將是日期值，帳戶值和專有分發代碼值。 例如：

example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C

這被認為是一個“RESTful”URL還是有更好的方法更有意義？ 任何輸入都非常感謝。

順便說一下，Python是首選語言。 謝謝！

Answer 1

根據定義，URI不能自己“unRESTful”，因為URI規范是由REST架構風格引導的。 如何使用 URI可能違反REST樣式：

1. 不遵循“客戶端 - 服務器”約束; 例如，通過使用WebSockets實現服務器推送。
2. 不遵循“資源識別”約束; 例如，使用URI的一部分來指定控制數據或資源元數據，而不是堅持識別資源，或者通過除URI之外的某種機制（如會話狀態或其他帶外機制）識別資源。
3. 不遵循“通過陳述來控制資源”的約束; 例如，通過使用URI的查詢字符串部分來傳輸狀態。
4. 不遵循“自描述信息”約束; 例如，使用HTTP GET修改狀態，或使用Content-Type為“text / html”傳輸JSON。
5. 不遵循“超媒體作為應用程序狀態引擎”的約束; 例如，不提供要跟隨的用戶代理超鏈接，而是假設它將使用帶外知識構造它們。
6. 不遵循“分層系統”約束，要求客戶端了解服務器工作方式的內部細節（特別是要求客戶端在請求中提供它們）。

以上都不一定是糟糕的選擇 。 它們可能是您系統的最佳選擇，因為它們可以培養某些架構屬性（例如效率或安全性）。 它們只是REST風格的一部分。

您的資源由多個必需段標識的事實是URI設計的重要組成部分。 正如Anton指出的那樣，在example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C和例如example.com/accounts/123/distributions/20030102/1A;1B;1C ; example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C ; example.com/accounts/123/distributions/20030102/1A;1B;1C之間的選擇純粹是數據設計之一，而不是URI層本身的問題。 例如，響應對前者的PUT，POST或DELETE請求沒有任何錯誤。 未能跟隨任何一個鏈接的客戶端將被視為已損壞。 期望通過除超媒體響應以外的某種方式使客戶端可用的系統將被視為“不可靠”。

Answer 2

最好先從資源方面創建RESTful API，而不是URI。 它與您的數據設計有關，而不是與您選擇的語言有關。

例如，您有一個分發資源。 您希望在基於Web的API中表示它，因此它需要具有適當的唯一資源標識符（URI）。 它應該簡單，可讀，並且不太可能改變。 這將是一個很好的例子：

http://example.com/api/distribution/<some_unique_id>

在將更多內容和層次結構放入URI之前，請三思而后行 。

隨着數據模型或身份驗證方案的發展，您不希望更改URI。 對於使用API​​的開發人員和開發人員來說，更改URI非常容易 。 因此，如果您需要將身份驗證傳遞給后端，您可能應該使用GET參數或HTTP標頭（例如，AWS S3 API 允許這兩者 ）。

過多地考慮GET參數（例如， http://example.com/api/distribution/?id=<some_unique_id> ： http://example.com/api/distribution/?id=<some_unique_id> ）似乎是一個壞主意，但IMO並不重要[0] - 只要您可以訪問API文檔並獲取最新信息。

[0]更新：至少對於只讀API。 對於CRUD API，正如@daniel指出的那樣，當您擁有上述第一個示例中的端點時，它會更方便。 這樣，您可以通過為/api/distribution/<id>各個資源啟用GET，PUT，DELETE以及POST到/api/distribution來創建新的發行版，從而很好地使用HTTP方法。

在研究答案時，發現了一個關於RESTful API的精彩演示： 設計HTTP接口和RESTful Web服務 。

Answer 3

RESTful方式是將數據表示為資源，而不是請求的參數：

example.com/distribution/123/20030102/1A;1B;1C

Answer 4

當你想到RESTful時，大多數時候你也應該考慮CRUD。

example.com/request/distribution?acct=123&date=20030102&distcode=1A;1B;1C

GET-Request可以顯示某些內容（CRUD中的R）。

但是你對CUD-Parts考慮了哪些URL？