本文總結api接口開發中的一些規範，避免在開發過程中出現‘選擇性’的問題。
| 描述 | 樣例 | 備註 |
|---|---|---|
| API 的根入口點應儘可能保持足夠簡單 | ① api.example.com/* ②example.com/api/* |
|
| 在 URL 中嵌入版本編號 | api.example.com/v1/* |
|
| URL 的命名規範： ①命名必須全部小寫；②資源路由的命名必須是名詞，並且是複數形式；③必須 優先使用 Restful 類型的 URL；④不能出現 -，必須 用下劃線 _ 代替；⑤必須 是易讀的；⑥一定不可 暴露服務器架構 | https://api.example.com/zoos https://api.example.com/animals https://api.example.com/zoos/{zoo}/animals https://api.example.com/animal_types https://api.example.com/employees |
|
| 請求方式：①刪除資源 必須 用 DELETE 方法；②創建新的資源 必須 使用 POST 方法；③更新資源 應該 使用 PUT 方法；④獲取資源信息 必須 使用 GET 方法； | - |
開發中常以：get請求只是用來查詢數據；post請求是用來增刪改數據 |
| 一些通用的參數名稱約定 | ①limit=1 指定返回記錄的數量； ②offset=10：指定返回記錄的開始位置；③page=2&per_page=100：指定第幾頁，以及每頁的記錄數； |
|
| 使用Access Token進行身份認證 | 應該 使用 OAuth2.0 的方式爲 API 調用者提供登錄認證。必須 先通過登錄接口獲取 Access Token 後再通過該 token 調用需要身份認證的 API。 | 也可以採用session的登錄機制 |
Response標準格式：
HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com
{
"code": 0,
"msg": "success",
"data": {
"username": "username"
}
}
or
{
"code": -1,
"msg": "該活動不存在",
}
常見的狀態返回碼：
| 狀態碼 | 描述 |
|---|---|
| 1xx | 代表請求已被接受，需要繼續處理 |
| 2xx | 請求已成功，請求所希望的響應頭或數據體將隨此響應返回 |
| 3xx | 重定向 |
| 4xx | 客戶端原因引起的錯誤 |
| 5xx | 服務端原因引起的錯誤 |
注：
1、只有來自客戶端的請求被正確的處理後才能返回 2xx 的響應，所以當 API 返回 2xx 類型的狀態碼時，前端 必須 認定該請求已處理成功。
2、所有 API 一定不可 返回 1xx 類型的狀態碼。
3、所有 API 一定不可 返回 3xx 類型的狀態碼。
4、狀態碼從100000開始，基本能滿足大部分的項目需求,而且可讀性強。
例如 ：
| 狀態碼 | 說明 |
|---|---|
| 0 | 請求成功 |
| 45**** | 實際業務中的狀態碼 |
| 400000 | 無效的簽名 |
| 404001 | 您查找的資源不存在 |
| 403001 | 權限不足 |
| 403002 | 用戶已禁用 |
| 405001 | 請求方法不被服務器允許 |
| 406001 | 不支持客戶端指定的數據格式 |
| 408001 | 客戶端請求超時 |
| 409001 | 狀態碼錶示因爲請求存在衝突無法處理，如：手機號已存在 |
| 410001 | 所請求的資源已不存在，並且未來也不會存在 |
| 413001 | 服務器拒絕處理當前請求，提交的實體數據大小超過了服務器願意或者能夠處理的範圍 |
| 414001 | 請求的 URI 長度超過了服務器能夠解釋的長度，因此服務器拒絕對該請求提供服務。 |
| 415001 | 通常表示服務器不支持客戶端請求首部 Content-Type 指定的數據格式。 |
| 429001 | 你操作太頻繁了（表示用戶請求次數超過允許範圍） |
| 500001 | 服務器出錯 |
| 503001 | 服務器暫時處於不可用狀態，當服務器需要維護或第三方 API 請求超時 / 不可達時 |
參考：
RESTful API 設計規範