整體規範建議採用RESTful 方式來實施。
協議
API與用戶的通信協議，總是使用HTTPs協議，確保交互數據的傳輸安全。
域名
應該儘量將API部署在專用域名之下。
https://api.example.com
如果確定API很簡單，不會有進一步擴展，可以考慮放在主域名下。
https://example.org/api/
api版本控制
應該將API的版本號放入URL。
https://api.example.com/v{n}/
另一種做法是，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。Github採用這種做法。
採用多版本並存，增量發佈的方式
v{n} n代表版本號,分為整形和浮點型
整形的版本號: 大功能版本發佈形式；具有當前版本狀態下的所有API接口 ,例如：v1,v2
浮點型：為小版本號，只具備補充api的功能，其他api都默認調用對應大版本號的api 例如：v1.1 v2.2
API 路徑規則
路徑又稱"終點"（endpoint），表示API的具體網址。
在RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞，而且所用的名詞往往與數據庫的表格名對應。一般來說，數據庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應該使用複數。
舉例來說，有一個API提供動物園（zoo）的信息，還包括各種動物和僱員的信息，則它的路徑應該設計成下面這樣。
https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees
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：獲取某個指定商品的指定投資者信息
過濾信息
如果記錄數量很多，服務器不可能都將它們返回給用戶。API應該提供參數，過濾返回結果。
下面是一些常見的參數。
?limit=10：指定返回記錄的數量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
?producy_type=1：指定篩選條件
API 傳入參數
參入參數分為4種類型：
地址欄參數
* restful 地址欄參數 /api/v1/product/122 122為產品編號，獲取產品為122的信息
* get方式的查詢字串 見過濾信息小節
請求body數據
cookie
request header
cookie和header 一般都是用於OAuth認證的2種途徑
返回數據
只要api接口成功接到請求，就不能返回200以外的HTTP狀態。
為了保障前後端的數據交互的順暢，建議規範數據的返回，並採用固定的數據格式封裝。
接口返回模板：
{
status:0,
data:{}||[],
msg:’’
}
status: 接口的執行的狀態
=0表示成功
<0 表示有異常=""
Data 接口的主數據
，可以根據實際返回數組或JSON對象
Msg
當status!=0 都應該有錯誤信息
非Restful Api的需求
由於實際業務開展過程中，可能會出現各種的api不是簡單的restful 規範能實現的，因此，需要有一些api突破restful規範原則。特別是移動互聯網的api設計，更需要有一些特定的api來優化數據請求的交互。
頁面級的api
把當前頁面中需要用到的所有數據通過一個接口一次性返回全部數據
舉例
api/v1/get-home-data 返回首頁用到的所有數據
這類API有一個非常不好的地址，只要業務需求變動，這個api就需要跟著變更。
自定義組合api
把當前用戶需要在第一時間內容加載的多個接口合併成一個請求發送到服務端，服務端根據請求內容，一次性把所有數據合併返回,相比於頁面級api，具備更高的靈活性，同時又能很容易的實現頁面級的api功能。
規範
地址：api/v1/batApi
傳入參數：
data:[
{url:'api1',type:'get',data:{...}},
{url:'api2',type:'get',data:{...}},
{url:'api3',type:'get',data:{...}},
{url:'api4',type:'get',data:{...}}
]
返回數據
{status:0,msg:'',
data:[
{status:0,msg:'',data:[]},
{status:-1,msg:'',data:{}},
{status:1,msg:'',data:{}},
{status:0,msg:'',data:[]},
]
}
Api共建平臺
RAP是一個GUI的WEB接口管理工具。在RAP中，您可定義接口的URL、請求&響應細節格式等等。通過分析這些數據，RAP提供MOCK服務、測試服務等自動化工具。RAP同時提供大量企業級功能，幫助企業和團隊高效的工作。
閱讀更多 架構師之旅 的文章
