API 接口可以說是軟件開發人員的用戶界面，API 設計也是系統架構的重要環節。尤其對複雜和分佈式系統而言，其設計的好壞，直接影響着整個系統的設計，實現和演進。一套糟糕的 API 設計也會嚴重影響使用者（開發人員）的心情和工作效率。
1. 使用HTTP Methods構建RESTful API
在HTTP協議中一共有九個HTTP Methods定義，分別是 GET、HEAD、POST、PUT、DELETE、TRACE、OPTIONS、CONNECT、PATCH，每個Http Method代表不同的用途和約定。在RESTful API 設計中，常用的有POST、GET、PUT、PATCH 和 DELETE，分別對應對資源的創建，獲取，修改，部分修改和刪除操作。下表簡單列出了這些Methods的用途和返回值約定。這是一個推薦的API設計與開發的最佳實踐和大多數現有 API 所遵守的約定。它本身並不是一個規範和強制標準。遵守約定和套路的好處是可以避免原則性設計缺陷，也可以讓經常使用此類 API 的開發者感覺熟悉和容易上手，否則你可能需要額外的文檔來解釋你的特殊設計，增加了使用者的負擔和學習成本。
| 序號 | HTTP方法 | 操作方式 | 示例 |
|---|---|---|---|
| 1 | POST | 創建數據 Create | /users |
| 2 | GET | 讀取數據 Read | /users/{id} 取一條數據; /users?limit=1&offset=10 取多條數據 |
| 3 | PUT | 修改數據 Update; 整條修改; 修改除ID外的所有屬性 |
/users/{id} 更新某一條數據 |
| 4 | PATCH | 修改數據 Update; 部分修改; 修改一條記錄的部分屬性 |
/users/{id} 更新部分數據 |
| 5 | DELETE | 刪除數據 Delete | /users/{id} 刪除某一條數據 |
其中 HEAD、TRACE、OPTIONS、CONNECT 在 RESTful API 設計中不常用，這些 Methods 具體定義可以在RFC2616規範中找到。如果需要，可以根據相關語意來實現具有對應功能的API。
2. API接口設計原則
API 命名應該採用約定俗成的方式，保持簡潔明瞭；
考慮到系統迭代和兼容性需求，API 中應該引入版本規則；
優雅的設計條件過濾、排序、搜索等傳入參數形式；
合理設計返回數據的形式，格式和考慮啓用壓縮（GZIP）；數據返回結果建議使用JSON；
根據不同的 API 操作，設置合適的 HTTP 狀態碼和必要的出錯信息；
使用 Token 機制設計鑑權和驗證系統(Authorization and Authentication)
如何實現數據的分頁返回；
如何處理有關聯資源的返回數據；
考慮啓用 HTTP 緩存機制，以改善網絡通信效率；
無狀態通信的會話狀態應該全部由客戶端負責維護；
分層系統通過限制組件的行爲（即每個組件只能看到與其交互的緊鄰層），將架構分解爲若干等級的接口層；
限制 API 調用頻次（Rate limiting）；
儘可能的使用 HTTPS，涉及用戶驗證的 API 一定要強制啓用 HTTPS。
3. 使用HTTP狀態碼和錯誤響應
目前存在一種情況，有很多開發人員將API接口返回狀態碼一直設爲200，然後在返回的數據裏面自定義一些狀態碼來表示服務器返回結果的狀態碼。由於RESTful API是直接使用的HTTP協議，所以建議API接口的返回狀態碼也要儘量使用HTTP協議的狀態碼。以下是關於HTTP狀態碼和錯誤響應的建議：
1. 對於數據錯誤
400：請求信息不完整或無法解析。
422：請求信息完整，但無效。
404：資源不存在。
409：資源衝突。
2. 對於鑑權錯誤
401：訪問令牌沒有提供，或者無效。
403：訪問令牌有效，但沒有權限。
3. 對於標準狀態
200： 所有的都正確。
500： 服務器內部拋出錯誤。