1.什麼是REST
REST全稱是Representational State Transfer,表述狀態轉移的意思。它是在Roy Fielding博士論文首次提出。REST本身沒有創造新的技術、組件或服務，它的理念就是在現有的技術之上，更好的使用現有的 web規範。用REST規範的web服務器，能夠更好的展現資源，客戶端能夠更好的使用資源。每個資源都由URI/ID標識。REST本身跟http無關，但是目前http是與它相關的唯一實例。REST有著優雅、簡潔的特性，本文是根據豆瓣api來談談自己對restful的一些理解。
2.URI規範
- URI(Uniform Resource Identifiers) 統一資源標示符
- URL(Uniform Resource Locator) 統一資源定位符
URI 的格式：
URI的格式定義如下：
URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]
- uri代表的是一種資源，要做到優雅、簡潔。
- 最好在api地址標明版本
比如
https://api.douban.com/v2
- 關於分隔符“／”，比如：
"/"分隔符一般用來對資源層級的劃分,比如：
https://api.douban.com/v2/book/1220562
表述了豆瓣api，version2下的圖書倉庫下的編號為1220562的圖書。
- URI儘量使用“-”代替下劃線“_“。
- URI統一使用小寫字母
- URI不包含文件擴展名
- 使用？用來過濾資源，比如？limit=10 :指定返回10條記錄。
- 不使用無意義的字符串、數字，要做到簡潔。
3.正確使用method
- get -只用做資源的讀取。
- post-通過用作創建一個新的資源。
- delete-通過用作資源的刪除。
- put -通過用作更新資源或者創建資源
- head-只獲取某個資源的頭部信息。
比如 豆瓣圖書api：
- 另外，在一些不符合curd的情況下，使用 post。
- 把動作轉換成資源
- 比如，上述接口中，用戶收藏某本書對外暴露的接口是”/v2/book/:id/collection”,收藏動作通過post方法來展現，而不直接寫著api中，collection “收藏”，名次，動作直接轉換成了資源。
4.選擇合適的狀態碼
http請求需要返回狀態碼，約定俗成的狀態碼能夠幫助開發團隊提高溝通效率。
- 2xx: 請求正常處理並返回
- 3xx: 重定向
- 4xx: 客戶端請求有錯誤
- 5xx: 服務端請求有錯誤
比如豆瓣api返回的狀態碼說明：
5.使用通用的錯誤碼
通用錯誤碼，具體產品由具體產品api給出。比如豆瓣api:
太多了，只列出幾條，具體見豆瓣 api。
6. 安全
這部分內容不屬於這篇文章，但是稍微說明下：
- 使用https
- 使用jwt驗證
- 使用參數簽名，防止參數被篡改。
- 使用權限驗證，shiro ,或者自己建數據庫（用戶、角色、權限）
7.api文檔
接口文檔的編寫至關重要，最好是寫一個在線接口文檔。接口文檔能夠方便團隊查閱，減少不必要的溝通。如果對外公開api，api文檔的質量直接反應了一個公司的技術水平，甚至一個公司的文化氣質。
本文參考了以下的資料:
豆瓣api
理解restful架構
restful introduction
跟著github學習restful api設計
REST接口設計規範
restful api 設計指南
分享到:
閱讀更多 架構師的修煉之路 的文章
