前端設備的多樣性促進API架構的流行，甚至出現“API優先”的設計思想。而RESTFUL API 是目前比較成熟的一套互聯網應用程序的API設計理論，如何設計一套合理好用的API，就是本篇文章的重點，廢話少說，開始正題。
1、協議
上篇已說到“RESTFUL是基於HTTP的設計風格和開發方式”
結論：API與用戶的通信協議，總是使用HTTP/HTTPS
2、域名：對外開放訪問的必須條件
優先將API放在專用域名下
API簡單且不會再進一步擴展時，可考慮放主域名下
3、版本：應該將API的版本放入URL中
相較於將版本信息放到HTTP頭信息中，體現在URL中更直觀
4、通過媒體類型指定版本信息
|
Accept：application/json |
5、路徑：路徑又稱“終點”，表示API的具體地址（限名詞）
注意事項：
（1）URL的命名必須全部小寫
（2）URL中的資源的命名必須是名詞且爲複數形式
（3）URL中不能出現-，必須用_替代
（4）URL必須是易讀的
（5）URL一定不可暴露服務器架構（如何理解）
6、HTTP動詞：表示資源的具體操作類型
常用動詞如下（括號裏對應的是SQL命令）
|
GET（SELECT） |
從服務器中取出資源（一項或多項） |
|
POST（CREATE） |
在服務器新建一個資源 |
|
PUT（UPDATE） |
在服務器更新資源（客戶端提供改編後的完整資源--整行數據） |
|
PATCH（UPDATE） |
在服務器更新資源（客戶端提供改變的屬性-部分字段） |
|
DELETE（DELETE） |
從服務中刪除資源 |
|
HEAD |
獲取資源的元素據 |
|
OPTIONS |
獲取信息，關於資源的哪些屬性是客戶端可以更改的 |
示例如下：
|
GET /tigers |
列出所有的老虎 |
|
POST /tigers |
增加一隻老虎 |
|
PUT /tigers/name |
更新某隻特定老虎的信息（提供某隻老虎的所有信息） |
|
PATCH tigers/name |
更新某隻老虎的信息（提供某隻老虎的部分信息） |
|
DELETE tigers/name |
刪除某隻特定的老虎 |
7、過濾信息：如果記錄數過多，服務器不可能返回所有的數據給用戶，可通過參數過濾返回結果
常見參數如下
|
?limit=10 |
指定返回記錄的數量 |
|
?offset=10 |
指定返回記錄的開始位置 |
|
?page=2&per_page=10 |
指定頁數及每頁記錄數 |
|
?sortby=name&order=asc |
指定返回結果排序規則 |
|
?name=tidd |
指定篩選條件 |
參數的設計允許存在冗餘，即允許API路徑和URL參數偶爾有重複，
如GET /tigers/tidd 與 GET /tigers?name=tidd
8、狀態碼
|
狀態碼 |
描述 |
|
1xx |
代表請求已被接受，需要繼續處理 |
|
2xx |
請求已成功，請求所希望的響應頭或數據體將隨此響應返回 |
|
3xx |
重定向 |
|
4xx |
客戶端原因引起的錯誤 |
|
5xx |
服務端原因引起的錯誤 |
更多狀態碼信息見“RESTFUL中HTTP狀態碼歸納”
9、認證：先獲取Access_Token，再通過Token調用身份認證的API
獲取token時必須在響應中包含失效時間的參數
|
{ "access_token"："xxxxxxx", "token_type"："login", "expires_in"：60 } |
客戶端在請求需要認證的API時，必須在請求頭Authorization中帶上access_token
|
Authorization：login xxxxx |
超過指定時間後，access_token過期，服務端應返回相關提示
10、返回結果
常見返回方式
（1）將錯誤放到HTTP響應頭
（2）將錯誤放到HTTP響應實體中
注意事項：
（1）API一定不可返回1xx類型狀態碼
（2）必須返回出錯的響應信息
參考資料：