Restful API設計規範

RESTFUL是一種網絡應用程式的設計風格和開發方式，基於HTTP，可以使用XML格式定義或JSON格式定義。RESTFUL適用於移動網際網路廠商作為業務使能接口的場景，實現第三方OTT調用行動網路資源的功能，動作類型為新增、變更、刪除所調用資源。

RESTFUL特點包括：

1、每一個URI代表1種資源；

2、客戶端使用GET、POST、PUT、DELETE4個表示操作方式的動詞對服務端資源進行操作：GET用來獲取資源，POST用來新建資源（也可以用於更新資源），PUT用來更新資源，DELETE用來刪除資源；

3、通過操作資源的表現形式來操作資源；

4、資源的表現形式是XML或者HTML；

5、客戶端與服務端之間的交互在請求之間是無狀態的，從客戶端到服務端的每個請求都必須包含理解請求所必需的信息。

在當前流行的前後端分離架構，人們發現原來這套用於超文本傳輸的協議是如此適合用於設計基於網際網路的api接口，基於http動詞以及標準的http status返回信息，能夠非常好地描述api的特性，並且可讀性非常好。更重要的是，由於http是事實上的網際網路通訊標準協議，基於rest設計的api接口，就好像你出國用英語和別人交流，完全不存在溝通障礙。
REST架構，從個人角度理解，核心做了兩件事情

• 資源定位
• 資源操作

其實從REST的定義中就能看出來，表述層對應的就是描述資源的位置（資源定位），狀態轉移就是對資源的狀態進行變更操作（增刪改查）
下面舉個實際的例子：
假設我們資料庫裡有一張User表，我們根據表建好了領域對象模型User，按照restful規範設計的接口應該是這樣的：

• 新增用戶

[POST] /users

• 修改用戶

[PUT] /users/{id}

• 刪除用戶

[DELETE] /users/{id}

• 查找全部用戶

[GET] /users

從這裡也能看出接口命名為對應表名的複數形式，並且[method] 是對應到如下

HTTP Method

rest的定義，第一條叫做資源定位，如果還不理解，那讓我們再想想URL的定義，叫做統一資源定位符，也就是說url是用來表示資源在網際網路上的位置的，所以說在url中不應該包含動詞，只能包含名詞。對資源的操作應該體現在http method上面，如果這樣理解還比較抽象的話，這裡不妨再打一個比方，比如在jane的網站有一張小汽車的圖片，地址是http://jane.com/img/car.jpg,現在jane想設計一個api接口，實現對這張圖片的刪除操作，這個api應該怎麼設計？根據rest的設計規範，很容易得出是

[DELETE] http://jane.com/img/car

嚴格地說，有些網址最後的".html"後綴名是不必要的，因為這個後綴名表示格式，屬於"表現層"範疇，而URI應該只代表"資源"的位置。它的具體表現形式，應該在HTTP請求的頭信息中用Accept和Content-Type欄位指定，這兩個欄位才是對"表現層"的描述。

除了HTTP METHOD,rest另外一套重要的規範就是HTTP STATUS，這套狀態碼規範定義了常規的api操作所可能產生的各種可能結果的描述，遵循這套規範，會使得你的api變得更加可讀，同時也便於各種網絡、基礎設施進行交易狀態監控。經常會用到的status code整理如下：

200 OK - [GET]：伺服器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。202 Accepted - [*]：表示一個請求已經進入後臺排隊（異步任務）204 NO CONTENT - [DELETE]：用戶刪除數據成功。400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，伺服器沒有進行新建或修改數據的操作，該操作是冪等的。401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。403 Forbidden - [*] 表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的。404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，伺服器沒有進行操作，該操作是冪等的。406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）。410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時，發生一個驗證錯誤。500 INTERNAL SERVER ERROR - [*]：伺服器發生錯誤，用戶將無法判斷發出的請求是否成功。

最後推薦大家github的api文檔：

完畢！！！

---