分享知識 傳遞快樂
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報文。在後期文章中會介紹到。
———————————
相互學習，共同進步
如有不足請留言指正
