根據豆瓣 API 了解Restful API

　　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位址标明版本

　　比如

　　api.douban/v2

　　關于分隔符“／”，比如：

　　"/"分隔符一般用來對資源層級的劃分,比如：

　　api.douban/v2/book/1220562

　　表述了豆瓣api，version2下的圖書倉庫下的編号為1220562的圖書。

　　URI盡量使用“-”代替下劃線“_“。

　　URI統一使用小寫字母

　　URI不包含檔案擴充名

　　使用？用來過濾資源，比如？limit=10 :指定傳回10條記錄。

　　不使用無意義的字元串、數字，要做到簡潔。

　　3.正确使用method

　　get -隻用做資源的讀取。

　　post-通過用作建立一個新的資源。

　　delete-通過用作資源的删除。

　　put -通過用作更新資源或者建立資源

　　head-隻擷取某個資源的頭部資訊。

　　比如 豆瓣圖書api：

　　namemethodapi擷取圖書資訊get/v2/book/:id使用者收藏某本圖書post/v2/book/:id/collection使用者修改對某本圖書的收藏put/v2/book/:id/collection使用者删除對某個圖書的收藏delete/v2/book/:id/collection

　　另外，在一些不符合curd的情況下，使用 post。

　　把動作轉換成資源

　　比如，上述接口中，

買二手手遊賬号平台

使用者收藏某本書對外暴露的接口是”/v2/book/:id/collection”,收藏動作通過post方法來展現，而不直接寫着api中，collection “收藏”，名次，動作直接轉換成了資源。

　　4.選擇合适的狀态碼

　　http請求需要傳回狀态碼，約定俗成的狀态碼能夠幫助開發團隊提高溝通效率。

　　2xx: 請求正常處理并傳回

　　3xx: 重定向

　　4xx: 用戶端請求有錯誤

　　5xx: 服務端請求有錯誤

　　比如豆瓣api傳回的狀态碼說明：

　　狀态碼含義說明200ok請求成功201created建立成功202accepted更新成功400bad request請求不存在401unauthorized未授權403forbidden禁止通路404not found資源不存在500internal server error内部錯誤

　　5.使用通用的錯誤碼

　　通用錯誤碼，具體産品由具體産品api給出。比如豆瓣api:

　　錯誤碼錯誤資訊含義999unknow_v2_error未知錯誤1000need_permission需要權限1001uri_not_found資源不存在…….…

　　太多了，隻列出幾條，具體見豆瓣 api。

　　6. 安全

　　這部分内容不屬于這篇文章，但是稍微說明下：

　　使用https

　　使用jwt驗證

　　使用參數簽名，防止參數被篡改。

　　使用權限驗證，shiro ,或者自己建資料庫（使用者、角色、權限）

　　7.api文檔

　　接口文檔的編寫至關重要，最好是寫一個線上接口文檔。接口文檔能夠友善團隊查閱，減少不必要的溝通。如果對外公開api，api文檔的品質直接反應了一個公司的技術水準，甚至一個公司的文化氣質。

　　8.參考資料

　　本文參考了以下的資料:

　　豆瓣api

　　了解restful架構

　　restful introduction

　　跟着github學習restful api設計

　　REST接口設計規範

　　restful api 設計指南

　　如果喜歡本篇文章，歡迎轉發、點贊。關注訂閱号「Web項目聚集地」，回複「技術博文」即可擷取更多圖文教程、技術博文、學習資源。