REST風格的Web服務：方法名稱，輸入參數和返回值？

Question

我正在嘗試開發一個簡單的REST API。我仍然試圖瞭解它的基本架構範例。我需要一些幫助，下面：

1. 「資源」應該是名詞，對不對？所以，我應該有「用戶」，而不是「getUser」，對嗎？

2. 我在一些API中看到了這種方法：www.domain.com/users/（返回列表），www.domain.com/users/user（針對用戶執行某些操作）。這種方法好嗎？

3. 在我見過的大多數例子中，輸入和輸出值通常只是名稱/值對（例如color ='red'）。如果我想發送或退回比這更復雜的東西，該怎麼辦？我是不是隻能處理XML？

4. 假設用戶/用戶/方法將PUT添加到系統中。什麼是輸入參數的好格式（假設所需的唯一字段是'用戶名'和'密碼'）？如果用戶成功，那麼這將是一個很好的迴應？如果用戶失敗（我想返回一條描述性錯誤信息）會怎麼樣？

5. 什麼是好的&簡單的認證方法&授權？我想限制大部分方法成功登錄的用戶。每次通話都傳遞用戶名/密碼好嗎？是否傳遞一個被認爲更安全的令牌（如果是的話，應該如何實現過期等）？

Answer 1

對於第1點，是的。名詞預計。

對於第2點，我期望/users給我一個用戶列表。我希望/users/123給我一個特定的用戶。

對於第3點，您可以返回任何東西。你的客戶可以指定它想要的。例如text/xml,application/json等通過使用HTTP請求標頭，你應該儘可能多地遵從該請求（雖然你可能只能處理，如text/xml - 這在許多情況下是合理的）。

對於第4點，我期望POST到創建一個新用戶。 PUT將更新一個現有的對象。要報告成功或錯誤，您應該使用現有的HTTP成功/錯誤代碼。例如200 OK。有關更多信息，請參見this SO answer。

Answer 2

REST最重要的約束是超媒體約束（「超文本作爲應用程序狀態的引擎」）。把你的Web應用程序想象成一個狀態機，其中每個狀態都可以被客戶端請求（例如GET/user/1）。一旦客戶端有一個這樣的狀態（想想：一個用戶在看網頁），它看到一堆它可以遵循的鏈接轉到應用程序中的下一個狀態。例如，可能存在來自「用戶狀態」的客戶端可以遵循的鏈接以進入詳細狀態。

這樣，服務器在運行時一次向客戶端呈現應用程序的狀態機一次。巧妙的是：由於狀態機在運行時一直處於狀態，因此服務器可以在運行時動態更改狀態機。

話雖如此......

on 1.資源實質上表示您想要呈現給客戶端的應用程序狀態。該常常會與域對象（例如用戶）緊密匹配，但要確保您明白您爲其提供的表示不僅僅是序列化的域對象，而是您的Web應用程序的狀態。

根據GET/users/123進行思考很好。不要在URI中放置任何操作。雖然沒有害處（它只是一個不透明的字符串），但至少可以說是令人困惑的。

2，正如Brian所說。您可能需要查看Atom發佈協議RFC（5023），因爲它很好地解釋了創建/讀取/更新週期。

on 3.關注面向文檔的消息。媒體類型是REST的重要組成部分，因爲它們提供了應用程序語義（完全）。做而不是使用泛型類型，如application/xml或application/json，因爲您將圍繞常見的隱式模式來耦合客戶端和服務器。如果沒有任何東西符合您的需求，只需製作您自己的類型。

也許你有興趣的例子我一起黑客利用UBL：http://www.nordsc.com/blog/?cat=13

在4通常情況下，使用POST /用戶/創造。看看RFC 5023 - 這將澄清這一點。這是一個容易理解的規範。

on 5.由於您無法使用會話（有狀態服務器）並且處於RESTful狀態，因此您必須在每個請求中發送憑據。各種HTTP認證方案已經處理了。關於緩存也很重要，因爲HTTP授權標頭具有特殊的指定語義緩存（無公共緩存）。如果你把你的憑證塞入cookie中，你會丟掉那個重要的部分。

所有的HTTP狀態碼都有一定的應用語義。使用它們，不要通過HTTP隧道自己的錯誤語義。

您可以訪問#rest IRC或加入雅虎討論討論。

1月