前言
網絡應用程序，分為前端和后端兩個部分。當前的發展趨勢，就是前端設備層出不窮（手機、平板、桌面電腦、其他專用設備......）。因此，必須有一種統一的機制，方便不同的前端設備與后端進行通信。這導致API構架的流行，甚至出現"API First"的設計思想。RESTful API是目前比較成熟的一套互聯網應用程序的API設計理論。
資源 （Resources）
URI (Uniform Resource Identifiers) 統一資源標示符
URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]
URI規范
URI不包含動詞，使用名詞復數。
URI不使用大寫。
URI層級不要太深。
URL(Uniform Resource Locator) 統一資源定位符(URI的實現)
表現（Representation）
HTTP請求的頭信息中，用Accept和Content-Type標示。
HTTP動詞
對于資源的具體操作類型，由HTTP動詞表示。
常用的HTTP動詞有下面五個（括號里是對應的SQL命令）。
- GET（SELECT）：從服務器取出資源（一項或多項）。
- POST（CREATE）：在服務器新建一個資源。
- PUT（UPDATE）：在服務器更新資源（客戶端提供改變后的完整資源）。
- PATCH（UPDATE）：在服務器更新資源（客戶端提供改變的屬性）。
- DELETE（DELETE）：從服務器刪除資源。
還有兩個不常用的HTTP動詞。
- HEAD：獲取資源的元數據。
- OPTIONS：獲取信息，關于資源的哪些屬性是客戶端可以改變的。
Restful api 一些例子:
- 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：刪除某個指定動物園的指定動物
過濾信息
如果記錄數量很多，服務器不可能都將它們返回給用戶。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 的含義是相同的。
常見異常返回碼
- 200 OK - [GET]：服務器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。
- 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。
- 202 Accepted - [*]：表示一個請求已經進入后臺排隊（異步任務）
- 204 NO CONTENT - [DELETE]：用戶刪除數據成功。
- 400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操作，該操作是冪等的。
- 401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。
- 403 Forbidden - [*] 表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的。
- 404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操作，該操作是冪等的。
- 406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）。
- 410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。
- 422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時，發生一個驗證錯誤。
-500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。
異步任務
由于互聯網通信 高延時（high latency）、高并發等特點 異步任務派上大用場。
- 先返回任務創建成功
- 客戶端輪詢任務狀態
