RESTful API的理解

RESTful API

目前的異步加載橫行的時候，異步請求已經遍地都是，而規定請求接口的時候，若是不能有很好的風格的話，不少時候會讓開發者誤解，一個好的API接口 設計須要注意如下：

1. 參數職責單一
2. 意圖清晰，便於開發者調用
3. 易於訪問者輸入

看是可是真的設計的時候常常會設計出不規範 的接口，

REST原則

REST 即Representational State Transfer的縮寫。它的理論比較抽象不太具體，理解它主要在於理解這些概念：資源、表現層、狀態轉換。
基於REST原則設計的API，通常稱爲 RESTFul API，須要遵照如下這些原則。

1. URL描述的是一個特定資源。所以描述須要名詞，不能出現動詞。由於動詞描述的再也不是資源自己，而是行爲
2. 利用HTTP請求的動詞表示對於資源操做的行爲

同時，對於URL的設計通常還有約定俗成的如下補充。

1. 對於資源的描述的名詞應該是層級嵌套的方式，好比 /company/department/projects。經過這種對於信息層級描述的方式，更利於實體的抽象，以及增長客戶端與服務器端開發人員對於整個系統模塊認知的一致性
2. 路徑終點的命名考慮用複數形式，好比 /books。通常一個URL路徑表示的資源會映射爲數據庫一系列表的記錄的集合，所以使用複數更直觀

實踐設計

實際設計restful api時的注意點包括如下：

1. 儘可能使用https協議
2. 若是接口是公用且會被擴展時，應該考慮放在專有域名下，https://api.baidu.com
3. 因爲api會在業務中不斷地迭代，因此最好是帶上版本，https://api.baidu.com/v2/
4. 最後接口路徑應該儘可能使用集合，也就是複數形式，https://api.baidu.com/v2/books

5. 操做類接口應該注意使用對應的動詞來操做

   GET /zoos：列出全部動物園
   POST /zoos：新建一個動物園
   GET /zoos/ID：獲取某個指定動物園的信息
   PUT /zoos/ID：更新某個指定動物園的信息（提供該動物園的所有信息）
   PATCH /zoos/ID：更新某個指定動物園的信息（提供該動物園的部分信息）
   DELETE /zoos/ID：刪除某個動物園
   GET /zoos/ID/animals：列出某個指定動物園的全部動物
   DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物

6. 參數，使用參數來進行篩選，?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
7. 返回結果，結果應該包括多種狀況，異常、錯誤信息、正確結果{status:'ok',massage:'ok',data:{data:1}}
8. 目前而言最好使用JSON格式傳輸數據。

參考：efe的restful理解，阮一峯restful api