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

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

　　一、協議

　　API與用戶的通信協議，總是使用HTTPs協議。

　　二、域名

　　應該盡量將API部署在專用域名之下。

　　https://api.example.com

　　如果確定API很簡單，不會有進一步擴展，可以考慮放在主域名下。

　　https://example.org/api/

　　三、版本(Versioning)

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

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

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

　　四、路徑(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

　　五、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：刪除某個指定動物園的指定動物

　　六、過濾信息(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 的含義是相同的。

RESTful API 設計指南