rest api(rest api設計原則)

要弄清楚什么是RESTful API，首先要弄清楚什么是REST？

01 REST

REprentational State Transfer，英語的直譯就是“表現層狀態轉移”。如果看這個概念，估計沒幾個人能明白是什么意思。那下面就讓我來用一句話解釋一下什么是RESTful：URL定位資源，用HTTP動詞（GET,POST,PUT,DELETE)描述操作。

Resource：資源，即數據。Reprentational：某種表現形式，比如用JSON，XML，JPEG等；State Transfer：狀態變化。通過HTTP動詞實現。

所以RESTful API就是REST風格的API。那么在什么場景下使用RESTful API呢？

在當今的互聯網應用的前端展示媒介很豐富。有手機、有平板電腦還有PC以及其他的展示媒介。那么這些前端接收到的用戶請求統一由一個后臺來處理并返回給不同的前端肯定是最科學和最經濟的方式，RESTful API就是一套協議來規范多種形式的前端和同一個后臺的交互方式。

RESTful API由后臺也就是SERVER來提供前端來調用。前端調用API向后臺發起HTTP請求，后臺響應請求將處理結果反饋給前端。也就是說RESTful 是典型的基于HTTP的協議。

02 RESTful API的設計原則和規范

資源首先是弄清楚資源的概念。資源就是網絡上的一個實體，一段文本，一張圖片或者一首歌曲。資源總是要通過一種載體來反應它的內容。文本可以用TXT，也可以用HTML或者XML、圖片可以用JPG格式或者PNG格式，JSON是現在最常用的資源表現形式。統一接口RESTful風格的數據元操CRUD（create,read,update,delete）分別對應HTTP方法：GET用來獲取資源，POST用來新建資源（也可以用于更新資源），PUT用來更新資源，DELETE用來刪除資源，這樣就統一了數據操作的接口。URI可以用一個URI（統一資源定位符）指向資源，即每個URI都對應一個特定的資源。要獲取這個資源訪問它的URI就可以，因此URI就成了每一個資源的地址或識別符。一般的，每個資源至少有一個URI與之對應，最典型的URI就是URL。無狀態所謂無狀態即所有的資源都可以URI定位，而且這個定位與其他資源無關，也不會因為其他資源的變化而變化。

有狀態和無狀態的區別，舉個例子說明一下：

例如要查詢員工工資的步驟為：

第一步：登錄系統

第二步：進入查詢工資的頁面

第三步：搜索該員工

第四步：點擊姓名查看工資

這樣的操作流程就是有狀態的，查詢工資的每一個步驟都依賴于前一個步驟，只要前置操作不成功，后續操作就無法執行。如果輸入一個URL就可以得到指定員工的工資，則這種情況就是無狀態的，因為獲取工資不依賴于其他資源或狀態，且這種情況下，員工工資是一個資源，由一個URL與之對應可以通過HTTP中的GET方法得到資源，這就是典型的RESTful風格。

說了這么多，到底RESTful長什么樣子的呢？

GET：http://www.xxx.com/source/id 獲取指定ID的某一類資源。例如GET:http://www.xxx.com/friends/123表示獲取ID為123的會員的好友列表。如果不加id就表示獲取所有會員的好友列表。POST：http://www.xxx.com/friends/123表示為指定ID為123的會員新增好友。其他的操作類似就不舉例了。

RESTful API還有其他一些規范：

應該將API的版本號放入URLGET:http://www.xxx.com/v1/friend/123?；蛘邔姹咎柗旁贖TTP頭信息中。我個人覺得要不要版本號取決于自己開發團隊的習慣和業務的需要，不是強制的。URL中只能有名詞而不能有動詞，操作的表達是使用HTTP的動詞GET,POST,PUT,DELETE。URL只標識資源的地址，既然是資源那就是名詞了如果記錄數量很多，服務器不可能都將它們返回給用戶。API應該提供參數，過濾返回結果。?limit=10：指定返回記錄的數量、?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。