RESTFul

參考：

• 理解RESTFul架構 http://mccxj.github.io/blog/20130530_introduce-to-rest.html
• RESTful API 設計指南 http://www.ruanyifeng.com/blog/2014/05/restful_api.html
• RFC2616 : Hypertext Transfer Protocol http://www.w3.org/Protocols/rfc2616/rfc2616.html

REST 自己只是一種架構風格，並不是具體標準，但 HTTP 能夠認爲是一份可參考的標準。正確的理解和應用的 HTTP 協議是該架構風格的一種實現，簡單理解就是：HTTP 用 URI 實現了 REST 的關鍵概念「資源」；用 GET/POST/PUT/PATCH/DELETE 等 METHOD 實現了 REST 的另外一個關鍵的統一接口的操做；用 status code 表示操做的結果。

當前的 RESTful API 實現 JSON over HTTP 佔絕對優點地位, 若溝通中出現「REST標準」，通常指的就是這種實現。

HTTP 中的 URI 是一個樹形的設計，有無限的邏輯擴展性。而 REST 自己又強調服務器是「無狀態」的，正確設計的狀況下，也能夠帶來近乎無限的物理擴展性（主要指水平擴展）。

資源是一個實體或者實體的集合（也是實體），每一種資源都有惟一而且和其它資源以相同原則組織的 URI 來標識，這個 URI 也叫 endpoint，而後在資源上使用統一的方法表達各類操做，如 POST 只是建立新資源不能用來獲取資源。

如何抽象資源是業務規劃的關鍵第一步，對業務的建模決定了咱們如何看待數據、運行時模塊和對它們的操做。此處的關鍵是：對業務的理解，開發能力和設計能力。應適當的結合並應用面向對象原則，但不宜過分。此處很是關鍵，這階段的設計應有多人確承認行性。

良好抽象的資源應該是有明確而不是模棱兩可定義的 URI，對 URI 定義有不易理解的部分要多加斟酌。URI 定義中的字符分割，推薦用「減號」而非下劃線。

插曲：MVCC（多版本併發控制），指同一個數據實體有多個版本之別，當讀時返回當前最新的版本，當有寫入請求時版本更新。在讀多寫少的場景下，能夠比全局鎖等手段提高性能。惟一的衝突發生在多個併發寫入請求時：A讀(ver=1)-B讀(ver=1)-A寫(ver1->ver2)-B寫（失敗,它想修改的是ver1，但如今已是ver2）。

插曲：冪等性，相似於分佈式一致性的概念，可參考 http://www.cnblogs.com/weidagang2046/archive/2011/06/04/idempotence.html

METHOD 完整定義參考：Method Definitions http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html，通常咱們只使用五種 METHOD ：

• GET ：從服務器獲取資源或者資源的集合，只讀，冪等，無反作用。
• POST ：在服務器新建一個資源，只寫，有反作用，會改變資源集合。
• PUT ：使用客戶端數據在服務器覆蓋式更新資源，併發場景建議使用 MVCC 保證一致性。
• PATCH ：客戶端提供部分數據，在服務器更新資源的一部分數據，一樣建議在併發場景使用 MVCC 保證一致性。
• DELETE ：從服務器刪除資源，可選使用 MVCC。

使用正確的方法作正確的操做是容易在實現上忽略的一點，在開發過程當中務必檢查方法的正確性，防止一個 GET 走天下的實現。

API 實現的動做必須由 METHOD 字段體現，而不能在 URI 中體現，簡單的說：URI 裏儘可能不要出現動詞。以下是大忌：

• GET /api/v1/create-entity?id=123&name=obc
• POST /api/v1/get-entity?id=123

正確的設計應該是：

• POST /api/v1/module/entity?name=obc&unique
• GET /api/v1/module/entity/123

總體 API 的實現包括 JSON 結構定義，可讀性是第一要素，儘可能作到自釋義。總體設計追求使用者能以最低的腦力代價無岐義的理解資源、屬性、操做、分類、條件、結果等。如有可能儘可能避免使用整形表達狀態或類型，如type:1改爲type:"udp"，result:0應改爲result:"success"。

若咱們有一個消息服務能夠這樣設計：

新建一個消息，新的消息是一個資源，會有一個惟一標識。dest/clientuuid參數表示目標和客戶端ID，客戶端ID的做用是在重試的時候實現服務器的無狀態需求：相同CID的請求被認爲是重複發送，若上次已經成功執行，則再也不執行動做直接返回結果。此處只接受 POST 命令，意爲在消息這個集合上的操做，只有新加入。若要執行刪除等操做，必須針對具體的單個消息。

• POST /api/v1/messages?dest=DEST&clientuuid=CID

獲取/修改/刪除 一條標識爲 123456 的消息，此處消息用整形數字來標識。該消息在執行 GET 時能夠經過 version 參數指定獲取不一樣的版本。在執行修改和刪除動做時，version 用來實現 MVCC 以保證冪等性。

• GET | PATCH | DELETE /api/v1/messages/123456?version=VERSION

也是新建一個消息，不一樣的是隻發給某個用戶 uid666。令牌機制（token）也是一種防止重複請求的方法，但這個 TOKEN 是服務器下發的並不是客戶端本身生成。能夠參考：https://6xiao.github.io/2017/0122.token.html

• POST /api/v1/user/uid666/messages?token=xxxxxxxxxxx

獲取某個用戶的私信消息列表，參數指定開始位置和獲取數量，比分頁設計更容易實現服務器的無狀態化。

• GET /api/v1/user/uid666/private?last=LASTID&count=COUNT

當執行完操做後，服務器務必返回能正確表達結果的狀態碼，如有錯誤須要在結果 JSON 中說明。經常使用狀態碼如：

• 200 ：成功
• 201 ：新資源建立成功
• 304 ：資源未更改
• 400 ：請求中的路徑、參數或者其它錯誤
• 404 ：資源不存在
• 500 ：服務器內部錯誤，應該在返回的 JSON 中表達緣由。

特定的狀態碼必須和實際狀況一致，一樣要避免一個 200 走天下。STATUS CODE 完整定義參考：Status Code Definitions http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html