000 RESTful Web Service設計的一般步驟
1. 規劃數據集
2. 將數據集劃分爲資源
3. 用URI爲資源命名
4. 暴露統一接口的子集
5. 設計來自客戶端的表示
6. 設計發給客戶端的表示
7. 用超鏈接把資源與已有資源鏈接起來
8. 考慮可能的錯誤
001 資源設計
1. 預定義的一次性資源,比如服務的主頁,主要就是服務的索引頁,或者目錄頁
2. 對應於數據項的資源,比如某個用戶的一篇日誌就是這樣一個資源
3. 在數據上的某個算法結果的資源,比如google出來的搜索結果,獲取某個用戶一段時間內的日誌都是這類資源
總的來說,如果每個數據項對應一個資源,那麼資源的一個子集也是資源,資源的索引(即目錄)也是資源,這取決於你想要
暴露的資源表面積。
資源設計還有一個需要考慮的問題,某一個數據你是需要把它設計爲某個或某些資源的屬性(子資源),還是直接暴露爲單獨
的資源。例如要描述兩個賬戶,它們分別是單獨的資源,現在有一筆轉賬要進行,最好的方式是將轉賬抽象爲資源,而不是分別
在賬戶的下面暴露兩個子資源,轉入和轉出,因爲這樣可以保證轉賬操作的原子性。
002 URI設計
服務URI的設計應該具有一定的意義和良好的設計,下面介紹幾個可以採用的設計原則
1. 資源暴露的URI應該是主體而非動作,比如要暴露一個提交事務的操作,/do-trasaction/是不適合的,好的設計是設計
/transaction 接口,然後用HTTP動詞PUT表示事務的提交
2. 用路徑變量對URI進行層次化的劃分,通常是從一般到特殊,比如某個用戶的某一篇文章可以表示爲
/{user-name}/{article-name},
3. 用逗號和分號分隔同一層次的並列內容,比如對於一個地圖服務,可能你需要查詢特定經緯度的地理信息,可能的設計是
/position/103.12,37.3
003 統一接口的設計
統一接口的設計是RESTful Web Service的一大特點,通過使用HTTP原有的動詞並賦予統一的意義,才能基於資源進行URI設計,
也就是說URI裏可以不包含操作信息,這也極大的降低了所需的URI的數量。
1. GET用於資源的獲取,
2. PUT用於添加新的資源或者修改資源的狀態,
3. DELETE用於刪除一個資源,
4. POST用於創建一個從屬資源,
004 資源鏈接的設計
沒有鏈接或者鏈接少的服務要求客戶端熟悉每一個資源對應URI的構造方式,而通過提供鏈接的方式可以一定程度上屏蔽資源表示的
變化,如果拿編程語言來類比的話就像通過函數或者類將某一些功能封裝起來,當你在使用服務的時候只需要循着鏈接往下就可以了,而
不需要熟悉每一個URI的構造方式。
005 返回值的設計
1. 創建一個資源後,服務器應返回響應代碼200('ok')或者異步情況返回201('Created'),並在Location報頭給出對應的URI
2. 修改一個資源後,服務器應返回200('OK'),加入本次修改導致了資源URI的改變,返回響應代碼301('Moved
Permanently'),並在Location報頭給出新URI
3. 刪除一個資源後,服務器應返回200('OK')
005 常見的錯誤返回
和統一接口部分的設計一樣,RESTful Web Service的錯誤表示也最大的重用HTTP本身的錯誤碼,下面介紹一些常用的錯誤碼。
1. 加入用戶沒有獲得授權或者授權錯誤,服務器應返回401('Unauthorized')
2. 對於請求造成了資源的衝突,服務器應返回409('Conflict')
3. 如果在請求時給出了無意義的參數,返回400('Bad Request')
4. 客戶端試圖獲取一個不存在的資源,返回404('Not Found')
5. 如果客戶端傳輸數據格式錯誤,返回415('Unsupported Media Type')
006 服務的版本化
服務的版本化是當服務規模變大,同時又需要重大的URI更改的時候需要考慮的問題。服務的版本化只需要在設計之初在URI的最頂
層加上版本標識就可以了,例如/v1/user/phone。