RESTful API 設計指南

 

　　網絡應用程序，分爲前端和後端兩個部分。當前的發展趨勢，就是前端設備層出不窮(手機、平板、桌面電腦、其餘專用設備……)。

　　所以，必須有一種統一的機制，方便不一樣的前端設備與後端進行通訊。這致使API構架的流行，甚至出現」API First」的設計思想。RESTful API是目前比較成熟的一套互聯網應用程序的API設計理論。本文就簡單介紹下RESTful API 的設計指南。

　　1、協議

　　API與用戶的通訊協議，老是使用HTTPs協議。

 

　　2、域名

　　應該儘可能將API部署在專用域名之下。

　　https://api.example.com

　　若是肯定API很簡單，不會有進一步擴展，能夠考慮放在主域名下。

　　https://example.org/api/

 

　　3、版本(Versioning)

　　應該將API的版本號放入URL。

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

　　另外一種作法是，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。Github採用這種作法。

 

　　4、路徑(Endpoint)

　　路徑又稱」終點」(endpoint)，表示API的具體網址。

　　在RESTful架構中，每一個網址表明一種資源(resource)，因此網址中不能有動詞，只能有名詞，並且所用的名詞每每與數據庫的表格名對應。通常來講，數據庫中的表都是同種記錄的」集合」(collection)，因此API中的名詞也應該使用複數。

　　舉例來講，有一個API提供動物園(zoo)的信息，還包括各類動物和僱員的信息，則它的路徑應該設計成下面這樣。

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

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

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

 

　　5、HTTP動詞

　　對於資源的具體操做類型，由HTTP動詞表示。

　　經常使用的HTTP動詞有下面五個(括號裏是對應的SQL命令)。

　　GET(SELECT)：從服務器取出資源(一項或多項)。

　　POST(CREATE)：在服務器新建一個資源。

　　PUT(UPDATE)：在服務器更新資源(客戶端提供改變後的完整資源)。

　　PATCH(UPDATE)：在服務器更新資源(客戶端提供改變的屬性)。

　　DELETE(DELETE)：從服務器刪除資源。

　　還有兩個不經常使用的HTTP動詞。

　　HEAD：獲取資源的元數據。

　　OPTIONS：獲取信息，關於資源的哪些屬性是客戶端能夠改變的。

　　下面是一些例子。

　　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、過濾信息(Filtering)

　　若是記錄數量不少，服務器不可能都將它們返回給用戶。API應該提供參數，過濾返回結果。

　　下面是一些常見的參數。

　　?limit=10：指定返回記錄的數量

　　?offset=10：指定返回記錄的開始位置。

　　?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。

　　?sortby=name&order=asc：指定返回結果按照哪一個屬性排序，以及排序順序。

　　?animal_type_id=1：指定篩選條件

　　參數的設計容許存在冗餘，即容許API路徑和URL參數偶爾有重複。好比，GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的。