協議

http
https（使用HTTPS協議，以確保交互數據的傳輸安全）

域名

專門的api應用使用獨立域名 https://api.example.com
簡單的可使用api前綴區分 https://www.example.com/api

版本控制

接口版本的控制，可以在程序發佈時，不同版本的業務邏輯在一定程度上避免受到影響。

https://api.example.com/v{n}

應該將API的版本號放入URL。
採用多版本並存，增量發佈的方式。
n代表版本號，分為整型和浮點型
整型：大功能版本，如v1、v2、v3 ...
浮點型：補充功能版本，如v1.1、v1.2、v2.1、v2.2 ...

URL規則

在RESTful架構中，每個網址代表一種資源(resource),所以網址中不能有動詞，只能有名詞。【所用的名詞往往與數據庫的表格名對應】
數據庫中的表一般都是同種記錄的"集合"(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 刪除某個商品 

 GET /v1/products/ID/purchases 列出某個指定商品的所有投資者
 GET /v1/products/ID/purchases/ID 獲取某個指定商品的指定投資者信息

方法命名也要具有一定規範

新增以“add”為前綴。例如add{XXX}
刪除以“delete”為前綴。例如delete{XXX}
修改以“updata”為前綴。例如updata{XXX}
獲取以“get”為前綴。例如get{XXX}
獲取以“get”為前綴、“List”為後綴。例如get{XXX}List
保存以“save”為前綴。例如save{XXX}
發送以“send”為前綴。例如send{XXX}
上傳以“upload”為前綴。例如upload{XXX}

請求參數

cookie
request header：可以存放requestId，token,加密字段等
請求body數據：針對入參數據，
後端必須做數據驗證
地址欄參數

響應格式

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：獲取數據失敗 | 操作失敗

前後端約定

後端

後端需要保證JSON格式的合法性，前端不對格式的合法性做判斷
金額格式：所有金額以元為單位，顯示性的後臺返回的是格式化之後的，例如：6,800
時間格式: 儘量以一致格式的字符串傳遞 2019-01-01 12:12:12
數據接口中定義的key集合是後端返回的子集，即key不缺失（參考數據格式，允許傳遞更多數據）
key使用駝峰命名，首字母小寫
空對象請使用[]
空列表請使用[]
空字符串請使用''
默認數字請使用0
儘量避免使用null undefined
響應頭Content-Type為"application/json; charset=UTF-8"
接口應該攜帶requestId唯一標示用來追蹤問題
敏感度高的數據，客戶端和服務器通過約定的算法，對傳遞的參數值進行簽名匹配，防止參數在請求過程中被抓取篡改。
包含用戶隱私的字段數據，需要加*號。如：手機號，身份證，用戶郵箱，支付賬號，郵寄地址等。

 "phone":"150*****000",
 "idCard":"3500**********0555", 
 "email":"40*****[email protected]"

前端

請求頭 application/x-www-form-urlencoded
請求字段使用駝峰命名，首字母小寫
一個頁面儘量只有一個拉取接口，減少類似這種的連續請求。
當請求需要緩存並且有需要及時更新的情況，可以分多個請求。

文檔

這個無需多說，在系統對接的時候，有文檔絕對是個福音。

儘量採用自動化接口文檔，可以做到在線測試，同步更新。
應包含：接口BASE地址、接口版本、接口模塊分類等。
每個接口應包含：接口地址：不包含接口BASE地址。請求方式: get、post、put、delete等。請求參數：數據格式【默認JSON、可選form data】、數據類型、是否必填、中文描述。響應參數：類型、中文描述。
特殊code映射碼錶