理解 RESTful API 設計規範

RESTful是目前最流行的API設計規範，它是用於Web數據接口的設計。從字面能夠看出，他是Rest式的接口，因此咱們先了解下什麼是Rest。

REST與技術無關，它表明的是一種軟件架構風格，REST它是 Representational State Transfer的簡稱，中文的含義是: "表徵狀態轉移" 或 "表現層狀態轉化"。它是基於HTTP、URI、XML、JSON等標準和協議，支持輕量級、跨平臺、跨語言的架構設計。

一. 理解爲何要使用RESTful API設計規範？

在好久之前，工做時間長的同窗確定經歷過使用velocity語法來編寫html模板代碼，也就是說咱們的前端頁面放在服務器端那邊進行編譯的，更準確的能夠理解爲 "先後端沒有進行分離"，那麼在那個時候，頁面、數據及模板渲染操做都是放在服務器端進行的，可是這樣作有一個很大的缺點是: 後期維護比較麻煩，前端開發人員還必須掌握velocity相關的語法。所以爲了解決這個問題慢慢就出現了先後端分離的思想: 即後端負責數據接口, 前端負責數據渲染, 前端只須要請求下api接口拿到數據，而後再將數據顯示出來。所以後端開發人員須要設計api接口，所以爲了統一規範: 社區就出現了 RESTful API 規範，其實該規範很早就有的，只是最近慢慢流行起來，RESTful API 能夠經過一套統一的接口爲全部web相關提供服務，實現先後端分離。

二. Rest設計原則

那麼怎麼樣能夠設計成REST的架構規範呢? 須要符合以下的一些原則：

1. 每個URI表明一種資源;
2. 同一種資源有多種表現形式(xml/json);
3. 全部的操做都是無狀態的。
4. 規範統一接口。
5. 返回一致的數據格式。
6. 可緩存(客戶端能夠緩存響應的內容)。

符合上述REST原則的架構方式被稱做爲 RESTful 規範。

理解爲何全部的操做須要無狀態呢?

http請求自己是無狀態的，它是基於 client-server 架構的，客戶端向服務器端發的每一次請求都必須帶有充分的信息可以讓服務器端識別到，請求的一些信息一般會包含在URL的查詢參數中或header中，服務器端可以根據請求的各類參數, 不須要保存客戶端的狀態, 直接將數據返回給客戶端。無狀態的優勢是：能夠大大提升服務器端的健狀性和可擴展性。客戶端能夠經過token來標識會話狀態。從而可讓該用戶一直保持登陸狀態。

理解規範統一的接口

Rest接口約束定義爲: 資源識別；請求動做；響應信息; 它表示經過uri表示出要操做的資源，經過請求動做(http method)標識要執行的操做，經過返回的狀態碼來表示此次請求的執行結果。

可能看上面的解釋還不夠理解，下面我經過本身的理解來解釋下上面的具體含義; 好比說，我在未使用Rest規範以前，咱們可能有 增刪改查 等接口，所以咱們會設計出相似這樣的接口: /xxx/newAdd (新增接口), /xxx/delete(刪除接口), /xxx/query (查詢接口), /xxx/uddate(修改接口)等這樣的。增刪改查有四個不一樣的接口，維護起來可能也很差，所以若是咱們如今使用Restful規範來作的話，對於開發設計來講可能就只須要一個接口就能夠了，好比設計該接口爲 /xxx/apis 這樣的一個接口就能夠了，而後請求方式(method)有 GET--查詢(從服務器獲取資源); POST---新增(從服務器中新建一個資源); PUT---更新(在服務器中更新資源)，DELETE---刪除(從服務器刪除資源)，PATCH---部分更新(從服務器端更新部分資源) 等這些方式來作，也就是說咱們使用RESTful規範後，咱們的接口就變成了一個了，要執行增刪改查操做的話，咱們只須要使用不一樣的請求動做(http method)方式來作就能夠了，而後服務器端返回的數據也能夠是相同的，只是咱們前端會根據狀態碼來判斷請求成功或失敗的狀態值來判斷。具體有那些狀態碼咱們下面會講解到。

理解返回一致的數據格式

服務器端返回的數據格式能夠是XML、或json. 或者直接返回狀態碼的方式。好比返回錯誤的格式json數據以下:

{
    "code": 401,
    "status": "error",
    "message": '用戶沒有權限',
    "data": null
}

返回正確的數據格式的json數據通常能夠爲以下:

{
    "code": 200,
    "status": "success",
    "data": [{
        "userName": "tugenhua",
        "age": 31
    }]
}

三. URL及參數設計規範

1. uri設計規範

1) uri末尾不須要出現斜槓/
2) 在uri中使用斜槓/是表達層級關係的。
3) 在uri中可使用鏈接符-, 來提高可讀性。
好比 http://xxx.com/xx-yy 比 http://xxx.com/xx_yy中的可讀性更好。
4) 在uri中不容許出現下劃線字符_.
5) 在uri中儘可能使用小寫字符。
6) 在uri中不容許出現文件擴展名. 好比接口爲 /xxx/api, 不要寫成 /xxx/api.php 這樣的是不合法的。
7) 在uri中使用複數形式。
具體能夠看：（https://blog.restcase.com/7-rules-for-rest-api-uri-design/）

在RESTful架構中，每一個uri表明一種資源，所以uri設計中不能使用動詞，只能使用名詞，而且名詞中也應該儘可能使用複數形式。使用者應該使用相應的http動詞 GET、POST、PUT、PATCH、DELETE等操做這些資源便可。

那麼在咱們未使用RESTful規範以前，咱們是以下方式來定義接口的，形式是不固定的，而且沒有統一的規範。好比以下形式:

http://xxx.com/api/getallUsers; // GET請求方式，獲取全部的用戶信息
http://xxx.com/api/getuser/1;   // GET請求方式，獲取標識爲1的用戶信息
http://xxx.com/api/user/delete/1 // GET、POST 刪除標識爲1的用戶信息
http://xxx.com/api/updateUser/1  // POST請求方式 更新標識爲1的用戶信息
http://xxx.com/api/User/add      // POST請求方式，添加新的用戶

如上咱們能夠看到，在未使用Restful規範以前，接口形式是不固定的，沒有統一的規範，下面咱們來看下使用RESTful規範的接口以下，二者之間對比下就能夠看到各自的優勢了。

http://xxx.com/api/users;     // GET請求方式 獲取全部用戶信息
http://xxx.com/api/users/1;   // GET請求方式 獲取標識爲1的用戶信息
http://xxx.com/api/users/1;   // DELETE請求方式 刪除標識爲1的用戶信息
http://xxx.com/api/users/1;   // PATCH請求方式，更新標識爲1的用戶部分信息
http://xxx.com/api/users;     // POST請求方式 添加新的用戶

如上咱們能夠看到，增刪改爲咱們都是使用同一個api接口，只是請求的方式 GET(查詢)、POST(新增)、DELETE(刪除)、PACTH(部分更新)來表明的是增刪改查操做的方式。而後開發獲取到該請求的header頭部信息，就能夠知道是什麼方式來請求數據的了。

2. HTTP請求規範

GET (SELECT): 查詢；從服務器取出資源.
POST(CREATE): 新增; 在服務器上新建一個資源。
PUT(UPDATE): 更新; 在服務器上更新資源(客戶端提供改變後的完整資源)。
PATCH(UPDATE): 更新；在服務器上更新部分資源(客戶端提供改變的屬性)。
DELETE(DELETE): 刪除; 從服務器上刪除資源。

3. 參數命名規範

參數推薦採用下劃線命名的方式。好比以下demo:

http://xxx.com/api/today_login // 獲取今天登陸的用戶。
http://xxx.com/api/today_login&sort=login_desc // 獲取今天登陸的用戶、登陸時間降序排序。

四. http狀態碼相關的

狀態碼範圍

客戶端的每一次請求, 服務器端必須給出迴應，迴應通常包括HTTP狀態碼和數據兩部分。

1xx: 信息，請求收到了，繼續處理。
2xx: 表明成功. 行爲被成功地接收、理解及採納。
3xx: 重定向。
4xx: 客戶端錯誤，請求包含語法錯誤或請求沒法實現。
5xx: 服務器端錯誤.

2xx 狀態碼

200 OK [GET]: 服務器端成功返回用戶請求的數據。
201 CREATED [POST/PUT/PATCH]: 用戶新建或修改數據成功。
202 Accepted 表示一個請求已經進入後臺排隊(通常是異步任務)。
204 NO CONTENT -[DELETE]: 用戶刪除數據成功。

4xx狀態碼

400：Bad Request - [POST/PUT/PATCH]: 用戶發出的請求有錯誤，服務器不理解客戶端的請求，未作任何處理。
401: Unauthorized; 表示用戶沒有權限(令牌、用戶名、密碼錯誤)。
403：Forbidden: 表示用戶獲得受權了，可是訪問被禁止了, 也能夠理解爲不具備訪問資源的權限。
404：Not Found: 所請求的資源不存在，或不可用。
405：Method Not Allowed: 用戶已經經過了身份驗證, 可是所用的HTTP方法不在它的權限以內。
406：Not Acceptable: 用戶的請求的格式不可得(好比用戶請求的是JSON格式，可是隻有XML格式)。
410：Gone - [GET]: 用戶請求的資源被轉移或被刪除。且不會再獲得的。
415: Unsupported Media Type: 客戶端要求的返回格式不支持，好比，API只能返回JSON格式，可是客戶端要求返回XML格式。
422：Unprocessable Entity: 客戶端上傳的附件沒法處理，致使請求失敗。
429：Too Many Requests: 客戶端的請求次數超過限額。

5xx 狀態碼

5xx 狀態碼錶示服務器端錯誤。

500：INTERNAL SERVER ERROR; 服務器發生錯誤。
502：網關錯誤。
503: Service Unavailable 服務器端當前沒法處理請求。
504：網關超時。

五. 統一返回數據格式

RESTful規範中的請求應該返回統一的數據格式。對於返回的數據，通常會包含以下字段:

1) code: http響應的狀態碼。
2) status: 包含文本, 好比：'success'(成功), 'fail'(失敗), 'error'(異常) HTTP狀態響應碼在500-599之間爲 'fail'; 在400-499之間爲 'error', 其餘通常都爲 'success'。 對於響應狀態碼爲 1xx, 2xx, 3xx 這樣的能夠根據實際狀況可要可不要。

當status的值爲 'fail' 或 'error'時，須要添加 message 字段，用於顯示錯誤信息。

3) data: 當請求成功的時候, 返回的數據信息。 可是當狀態值爲 'fail' 或 'error' 時，data僅僅包含錯誤緣由或異常信息等。

返回成功的響應JSON格式通常爲以下:

{
    "code": 200,
    "status": "success",
    "data": [{
        "userName": "tugenhua",
        "age": 31
    }]
}

返回失敗的響應json格式爲以下:

{
    "code": 401,
    "status": "error",
    "message": '用戶沒有權限',
    "data": null
}