什麼是Restful API架構

分享知識 傳遞快樂

1、什麼是RESTful 

1）REST與技術無關，代表的是一種軟體架構風格（REST是Representational State Transfer的簡稱，中文翻譯為“表征狀态轉移”）

2）REST從資源的角度類審視整個網絡，它将分布在網絡中某個節點的資源通過URL進行辨別

3）所有的資料，不過是通過網絡擷取的還是操作（增删改查）的資料，都是資源，将一切資料視為資源是REST差別與其他架構風格的最本質屬性

4）對于REST這種面向資源的架構風格，有人提出一種全新的結構理念，即：面向資源架構（ROA：Resource Oriented Architecture）

2、了解什麼是API

什麼是API？

API就是接口，提供的url。接口有兩個用途：

• 為别人提供服務
• 前後端分離，一個寫vue，一個寫後端，他們之間都是通過ajax請求

3、主要的設計原則

• 資源與URI
• 統一資源接口(HTTP方法如GET，PUT和POST)
• 資源的表述
• 資源的連結
• 狀态的轉移

4、RESTful API設計規範

1）使用協定

API與使用者的通信協定，總是使用HTTPS協定。

2）域名

有兩種方式

方式一： 盡量将API部署在專用域名（會存在跨域問題）

https://api.example.com      

方式二：如果确定API很簡單，不會有進一步擴充，可以考慮放在主域名下。

https://example.org/api/      

3）版本

API版本一般放在URL中，簡潔明了，例：

https://api.example.com/v1/      

另一種做法是，将版本号放在HTTP頭資訊中，但不如放入URL友善和直覺。Github采用這種做法。

4）參數命名規範

可以采用駝峰命名法，也可以采用下劃線命名的方式，推薦采用下劃線命名的方式，使用采用下劃線的的方式識别度更高。

5）URL命名規範

API 命名為保持簡潔明了，應該采用約定俗成的方式。在RESTful架構中，每個URL代表一種資源，是以URL中均使用名詞表示（可複數）。

下面參考一下規範的URL和不規範的URL做個對比：

不規範的的url，形式不固定，可讀性不強，增加維護和閱讀成本，不同的開發者需要了解文檔才能調用。

https://www.api.com/api/getallUsers GET 擷取所有使用者 
https://www.api.com/api/getuser/1 GET 擷取辨別為1使用者資訊 
https://www.api.com/api/user/delete/1 GET/POST 删除辨別為1使用者資訊 
https://www.api.com/api/updateUser/1 POST 更新辨別為1使用者資訊 
https://www.api.com/api/User/add POST 添加新的使用者      

規範後的RESTful風格的url，形式固定，可讀性強，根據名詞就可以清楚的知道在操作哪些資源。

https://www.api.com/api/users GET 擷取所有使用者資訊 
https://www.api.com/api/users/1 GET 擷取辨別為1使用者資訊 
https://www.api.com/api/users/1 DELETE 删除辨別為1使用者資訊 
https://www.api.com/api/users/1 Patch 更新辨別為1使用者部分資訊,包含在body中 
https://www.api.com/api/users POST 添加新的使用者      

6）HTTP動詞

對于資源的具體操作類型，由HTTP動詞表示。常用的HTTP動詞有下面五個（括号裡是對應的SQL指令）。了解​​常見HTTP請求方法​​。

GET（SELECT）：從伺服器取出資源（一項或多項）。即擷取資料
POST（CREATE）：在伺服器建立一個資源。 即添加資料
PUT（UPDATE）：在伺服器更新資源（用戶端提供改變後的完整資源）。即更新資料
PATCH（UPDATE）：在伺服器更新資源（用戶端提供改變的屬性）。即更新資料
DELETE（DELETE）：從伺服器删除資源  。即删除資料      

下面是一些例子：

GET /users：列出所有使用者
POST /users：建立一個使用者
GET /users/ID：擷取某個指定使用者的資訊
PUT /users/ID：更新某個指定使用者的資訊（提供該使用者的全部資訊）
PATCH /users/ID：更新某個指定使用者的資訊（提供該使用者的部分資訊）
DELETE /users/ID：删除某個使用者
GET /users/ID/infos：列出某個指定使用者的所有資訊
DELETE /users/ID/infos/ID：删除某個指定使用者的指定資訊      

7）過濾資訊

https://www.api.com/v1/users?limit=10：指定傳回記錄的數量
https://www.api.com/v1/users?offset=10：指定傳回記錄的開始位置
https://www.api.com/v1/users?page=2&per_page=100：指定第幾頁，以及每頁的記錄數
https://www.api.com/v1/users?sortby=name&order=asc：指定傳回結果按照哪個屬性排序，以及排序順序
https://www.api.com/v1/users?animal_type_id=1：指定篩選條件      

8）傳回結果

針對不同操作，伺服器向使用者傳回的結果應該符合以下規範：

GET /collection：傳回資源對象的清單（數組）
GET /collection/resource：傳回單個資源對象
POST /collection：傳回新生成的資源對象
PUT /collection/resource：傳回完整的資源對象
PATCH /collection/resource：傳回完整的資源對象
DELETE /collection/resource：傳回一個空文檔      

統一傳回資料格式

對于合法的請求應該統一傳回資料格式，這裡隻說明一下JSON的方式：

• code：包含一個整數類型的HTTP響應狀态碼。
• status：包含文本：”success”，”fail”或”error”。
• message：當狀态值為”fail”和”error”時有效，用于顯示錯誤資訊。參照國際化（il8n）标準，它可以包含資訊号或者編碼，可以隻包含其中一個，或者同時包含并用分隔符隔開。
• data：包含響應的body。當狀态值為”fail”或”error”時，data僅包含錯誤原因或異常名稱、或者null也是可以的傳回成功的響應json格式

傳回成功的響應

{
  "code": 200,
  "message": "success",
  "data": {
    "userName": "abc",
    "age": 16,
    "address": "cn"
  }
}      

傳回失敗的響應

{
  "code": 401,
  "message": "error",
  "data": null
}      

9）Hypermedia API  超媒體API

RESTful API最好做到Hypermedia，即傳回結果中提供連結，連向其他API方法，使得使用者不查文檔，也知道下一步應該做什麼。

比如，當使用者向api.example.com的根目錄送出請求，會得到這樣一個文檔。

{"link": {
  "rel":   "collection https://www.example.com/zoos",  #表示這個API與目前網址的關系
  "href":  "https://api.example.com/zoos",  #API路徑
  "title": "List of zoos",  #API的标題
  "type":  "application/vnd.yourformat+json"  #傳回類型
}}      

Hypermedia API的設計被稱為HATEOAS。Github的API就是這種設計，通路api.github.com會得到一個所有可用API的網址清單。

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  // ...
}      

從上面可以看到，如果想擷取目前使用者的資訊，應該去通路api.github.com/user，然後就得到了下面結果。

{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}      

提示：從個從研發習慣比較喜歡服務間通路用XML封包請求和響應，但響應頁面或ajax時用JSON封包。在後期文章中會介紹到。