API接口規范(試行版)

1.協議

API與用戶的通信協議，總是使用HTTPS協議，確保交互數據的傳輸安全。

2.安全

為了保證接口接收到的數據不是被篡改以及防止信息泄露造成損失，對敏感數據進行加密及簽名。
數據加密
api接口請求參數一律采用RSA進行加解密，在客戶端使用公鑰對請求參數進行加密，在服務端使用對數私鑰據進行解密，防止信息泄露。
簽名
為了防止請求數據在網絡傳輸過程中被惡意篡改，對所有非查詢接口增加數字簽名，簽名原串為對請求參數進行自然排序，通過私鑰加簽后放入sign參數中。
時間戳
api接口中增加時間戳timestamp字段，作用：固定時間范圍內，減少同一請求被暴力調用的次數。

3.API版本控制

API的版本號統一放入URL。
https://api.example.com/v{n}/
v{n}n代表版本號，分為整形和浮點型
整形版本號：大功能版本發布形式；具有當前版本狀態下的所有API接口，例如：v1,v2
浮點型：為小版本號，只具備補充api的功能，其他api都默認調用大版本號的API，例如v1.1,v1.2

4.API路徑規則

在RESTful架構中，每個網址代表一種資源(resource)，所以網址中不能有動詞，只能有名詞。名詞盡量與數據庫表格名對應。
例子:

https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees

5.HTTP請求方式

對於資源的具體操作類型，由HTTP動詞表示。
常用的HTTP動詞由下面四個(括號里是對應的SQL命令)。
GET(SELECT):從服務器取出資源。
POST(CREATE):在服務器新建一個資源。
PUT(UPDATE):在服務器更新資源。
DELETE(DELETE):從服務器刪除資源。
例子:
GET/product:列出所有商品
POST/product:新建一個商品
GET/product/ID:獲取某個指定商品的信息
PUT/product/ID:更新某個指定商品的信息
DELETE/product/ID:刪除某個商品
GET/product/ID/purchase:列出某個指定商品的所有投資者
GET/product/ID/purchase/ID:獲取某個指定商品的指定投資者信息

6.請求數據

公共請求參數

參數名稱	參數類型	是否必填	最大長度	描述	示例
charset	String	是	10	請求使用的編碼格式如:utf-8,gbk	utf-8
sign_type	String	是	10	生成簽名字符串所使用的算法類型	RSA
sign	String	是	344	請求參數簽名串	djdu7dusufiusgfu
timestamp	String	是	14	發送請求的時間,格式:yyyyMMddHHmmss	20180505121212
requestSource	String	否	8	客戶端請求來源APP WAP PC	APP
token	String	否		鑒權標識，用於登錄判斷
biz_content	String	是		請求參數集合，除公共參數外所有請求參數

請求參數(biz_content)

參數名稱	參數類型	是否必填	最大長度	描述	示例
phone	String	是	10	登錄手機號	15088890908
phoneCode	String	是	6	驗證碼	234567

7.返回數據

為了保障前后端的數據交互的順暢，統一接口返回模板如下:

{
    code:0000,
    data:{},
    msg:''
}

code:接口的執行狀態
0000：表示成功
其他：不太異常
Data接口的主數據
返回JSON對象
Msg信息
當code!=0000都應該有錯誤信息

8.非RESTful API需求

由於實際業務開展過程中，可能會出現各種的api不是簡單的restful規范能實現的，因此需要一些api突破restful規范原則。

8.1頁面級API

把當前頁面中需要用到的所有數據通過一個接口一次性返回全部數據。
例子:
api/v1/get-home-data返回首頁用到的所有數據
此類API存在缺陷:只要業務需求變動，該api就需要跟着變更。

8.2自定義組合API

把當前用戶需要在第一時間內容加載的多個接口合並成一個請求發送到服務端，服務端根據請求內容，一次性把所有數據合並返回，相比於頁面級API，具備更高的靈活性，同時又能很容易實現頁面級API功能。
規范
地址:api/v1/testApi
傳入參數:

data:[
{url:'api1',type:'get',data:{}},
{url:'api2',type:'get',data:{}},
{url:'api3',type:'get',data:{}},
]

返回數據

{
  code:0000,
  msg:'',
  data:[
      {code:0000,msg:'',data:[]},
      {code:0000,msg:'',data:[]},
      {code:0000,msg:'',data:[]},
  ]
}

9.API共建平台

RAP是一個GUI的WEB接口管理工具。在RAP中，可定義接口的URL、請求&響應格式等等。通過分析這些數據，RAP提供MOCK服務、測試服務等自動化工具。

9.1什么是RAP?

在前后端分離的開發模式下，我們通常需要定義一份接口文檔來規范接口的具體信息。如請求地址、有幾個參數、參數名稱及類型含義等等。RAP首先方便團隊錄入、查看和管理這些接口文檔，並通過分析結構化的文檔數據，重復利用並生成自測數據、提供自測控制台等等。

9.2RAP的特色

通過RAP來管理API文檔。
提供MOCK服務，通過MockJS創建mock測試數據。

參考文獻