一、協議
API與客戶端用戶的通信協議，總是使用HTTPS協議，以確保交互數據的傳輸安全。
二、域名
應該盡量將API部署在專用域名之下： https://api.example.com 如果確定API很簡單,不會有進一步擴展,可以考慮放在主域名下： https://www.example.com/api
三、版本控制
https://api.example.com/v{n}
1、應該將API的版本號放入URL。
2、采用多版本並存，增量發布的方式。
3、n代表版本號，分為整型和浮點型 整型： 大功能版本， 如v1、v2、v3 ... 浮點型： 補充功能版本， 如v1.1、v1.2、v2.1、v2.2 ...
4、對於一個 API 或服務，應在生產中最多保留 3 個最詳細的版本
四、路徑規則
路徑又稱"終點"（end point），表示API的具體網址。
1、在RESTful架構中，每個網址代表一種資源(resource),所以網址中不能有動詞，只能有名詞。 【所用的名詞往往與數據庫的表格名對應】
2、數據庫中的表一般都是同種記錄的"集合"(collection),所以API中的名詞也應該使用復數。 例子: https://api.example.com/v1/products https://api.example.com/v1/users https://api.example.com/v1/employees
五、請求方式
GET（SELECT）： 從服務器取出資源（一項或多項）。
POST（CREATE）： 在服務器新建一個資源。
PUT（UPDATE）： 在服務器更新資源（客戶端提供改變后的完整資源）。
DELETE（DELETE）： 從服務器刪除資源。
例子： GET /v1/products 獲取所有商品 GET /v1/products/ID 獲取某個指定商品的信息 POST /v1/products 新建一個商品 PUT /v1/products/ID 更新某個指定商品的信息 DELETE /v1/products/ID 刪除某個商品,更合理的設計詳見【9、非RESTful API的需求】 GET /v1/products/ID/purchases 列出某個指定商品的所有投資者 GET /v1/products/ID/purchases/ID 獲取某個指定商品的指定投資者信息
六、過濾信息
若記錄數量很多，服務器不可能返回全部記錄給用戶。 API應該提供分頁參數及其它篩選參數，過濾返回結果。 /v1/products?page=1&pageSize=20 指定第幾頁，以及每頁的記錄數。 /v1/products?sortBy=name&order=asc 指定返回結果按照哪個屬性排序，以及排序順序。
七、傳入參數
傳入參數分為4種類型：
1、cookie： 一般用於OAuth認證
2、request header： 一般用於OAuth認證
3、請求body數據：
4、地址欄參數： 1）restful 地址欄參數 /v1/products/ID ID為產品編號，獲取產品編號為ID的信息 2）get方式的查詢字段 見【六、過濾信息】
八、響應參數
response： ---------------------------------------- { status: 200, // 詳見【status】 data: { code: 1, // 詳見【code】 data: {} || [], // 數據 message: '成功', // 存放響應信息提示,顯示給客戶端用戶【須語義化中文提示】 sysMessage: 'success' // 存放響應信息提示,調試使用,中英文都行 ... // 其它參數，如 total【總記錄數】等 }, msg: '成功', // 存放響應信息提示,顯示給客戶端用戶【須語義化中文提示】 sysMsg: 'success' // 存放響應信息提示,調試使用,中英文都行 } ---------------------------------------- 【status】: 200: OK 400: Bad Request 500：Internal Server Error 401：Unauthorized 403：Forbidden 404：Not Found 【code】: 1: 獲取數據成功 | 操作成功 0：獲取數據失敗 | 操作失敗
九、非RESTful API的需求
1、實際業務開展過程中，可能會出現各種的api不是簡單的restful 規范能實現的。 2、需要有一些api突破restful規范原則。 3、特別是移動互聯網的api設計，更需要有一些特定的api來優化數據請求的交互。 1)、刪除單個 | 批量刪除 ： DELETE /v1/product body參數{ids：[]} 2)、頁面級API : 把當前頁面中需要用到的所有數據通過一個接口一次性返回全部數據
十、一致性原則
1、前端需要哪些字段，API接口應該返回哪些字段，字段不多也不少。 2、更新功能盡量做到：初次返回的原始數據參數與提交更新的數據參數結構一致。 3、時間參數，盡量以一致格式的字符串傳遞， 如： ‘2019-01’ | ‘2019/01’ ‘2019-01-01’ | ‘2019/01/01’ ‘2019-01-01 12:12:12’ | ‘2019/01/01 12:12:12’ 4、其它參數【待更新】
十一、接口文檔
1、盡量采用自動化接口文檔，可以做到在線測試，同步更新。 2、應包含：接口BASE地址、接口版本、接口模塊分類等。 3、每個接口應包含： 接口地址：不包含接口BASE地址。 請求方式: get、post、put、delete等。 請求參數：數據格式【默認JSON、可選form data】、數據類型、是否必填、中文描述。 響應參數：類型、中文描述。
十二、參考資料
1、https://my.oschina.net/qqlet/blog/1922038
2、https://juejin.im/post/5afee0e86fb9a07ab379b371