整體規(guī)范建議采用RESTful 方式來實(shí)施滨溉。
協(xié)議
API與用戶的通信協(xié)議，總是使用HTTPs協(xié)議长赞，確保交互數(shù)據(jù)的傳輸安全晦攒。
域名
應(yīng)該盡量將API部署在專用域名之下。
https://api.example.com
如果確定API很簡(jiǎn)單得哆，不會(huì)有進(jìn)一步擴(kuò)展脯颜，可以考慮放在主域名下。
https://example.org/api/
api版本控制
應(yīng)該將API的版本號(hào)放入U(xiǎn)RL贩据。
https://api.example.com/v{n}/
另一種做法是栋操，將版本號(hào)放在HTTP頭信息中，但不如放入U(xiǎn)RL方便和直觀饱亮。Github采用這種做法矾芙。
采用多版本并存，增量發(fā)布的方式
v{n} n代表版本號(hào),分為整形和浮點(diǎn)型
整形的版本號(hào): 大功能版本發(fā)布形式近上；具有當(dāng)前版本狀態(tài)下的所有API接口 ,例如：v1,v2
浮點(diǎn)型：為小版本號(hào)剔宪，只具備補(bǔ)充api的功能，其他api都默認(rèn)調(diào)用對(duì)應(yīng)大版本號(hào)的api 例如：v1.1 v2.2
API 路徑規(guī)則
路徑又稱"終點(diǎn)"（endpoint），表示API的具體網(wǎng)址葱绒。
在RESTful架構(gòu)中感帅，每個(gè)網(wǎng)址代表一種資源（resource），所以網(wǎng)址中不能有動(dòng)詞地淀，只能有名詞失球，而且所用的名詞往往與數(shù)據(jù)庫的表格名對(duì)應(yīng)。一般來說帮毁，數(shù)據(jù)庫中的表都是同種記錄的"集合"（collection）她倘，所以API中的名詞也應(yīng)該使用復(fù)數(shù)。
舉例來說作箍，有一個(gè)API提供動(dòng)物園（zoo）的信息，還包括各種動(dòng)物和雇員的信息前硫，則它的路徑應(yīng)該設(shè)計(jì)成下面這樣胞得。
https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees
HTTP請(qǐng)求方式
對(duì)于資源的具體操作類型，由HTTP動(dòng)詞表示屹电。
常用的HTTP動(dòng)詞有下面四個(gè)（括號(hào)里是對(duì)應(yīng)的SQL命令）阶剑。
GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）。
POST（CREATE）：在服務(wù)器新建一個(gè)資源危号。
PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）牧愁。
DELETE（DELETE）：從服務(wù)器刪除資源。
下面是一些例子外莲。
GET /product：列出所有商品
POST /product：新建一個(gè)商品
GET /product/ID：獲取某個(gè)指定商品的信息
PUT /product/ID：更新某個(gè)指定商品的信息
DELETE /product/ID：刪除某個(gè)商品
GET /product/ID/purchase ：列出某個(gè)指定商品的所有投資者
get /product/ID/purchase/ID：獲取某個(gè)指定商品的指定投資者信息
過濾信息
如果記錄數(shù)量很多猪半，服務(wù)器不可能都將它們返回給用戶。API應(yīng)該提供參數(shù)偷线，過濾返回結(jié)果磨确。
下面是一些常見的參數(shù)。
?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開始位置声邦。
?page=2&per_page=100：指定第幾頁乏奥，以及每頁的記錄數(shù)。
?sortby=name&order=asc：指定返回結(jié)果按照哪個(gè)屬性排序亥曹，以及排序順序邓了。
?producy_type=1：指定篩選條件
API 傳入?yún)?shù)
參入?yún)?shù)分為4種類型：
地址欄參數(shù)
- restful 地址欄參數(shù) /api/v1/product/122 122為產(chǎn)品編號(hào)，獲取產(chǎn)品為122的信息
- get方式的查詢字串 見過濾信息小節(jié)
請(qǐng)求body數(shù)據(jù)
cookie
request header
cookie和header 一般都是用于OAuth認(rèn)證的2種途徑
返回?cái)?shù)據(jù)
只要api接口成功接到請(qǐng)求媳瞪，就不能返回200以外的HTTP狀態(tài)骗炉。
為了保障前后端的數(shù)據(jù)交互的順暢，建議規(guī)范數(shù)據(jù)的返回材失，并采用固定的數(shù)據(jù)格式封裝痕鳍。
接口返回模板：
{
status:0,
data:{}||[],
msg:’’
}
status: 接口的執(zhí)行的狀態(tài)
=0表示成功
<0 表示有異常=""
Data 接口的主數(shù)據(jù)
，可以根據(jù)實(shí)際返回?cái)?shù)組或JSON對(duì)象
Msg
當(dāng)status!=0 都應(yīng)該有錯(cuò)誤信息
非Restful Api的需求
由于實(shí)際業(yè)務(wù)開展過程中，可能會(huì)出現(xiàn)各種的api不是簡(jiǎn)單的restful 規(guī)范能實(shí)現(xiàn)的笼呆，因此熊响，需要有一些api突破restful規(guī)范原則。特別是移動(dòng)互聯(lián)網(wǎng)的api設(shè)計(jì)诗赌，更需要有一些特定的api來優(yōu)化數(shù)據(jù)請(qǐng)求的交互汗茄。
頁面級(jí)的api
把當(dāng)前頁面中需要用到的所有數(shù)據(jù)通過一個(gè)接口一次性返回全部數(shù)據(jù)
舉例
api/v1/get-home-data 返回首頁用到的所有數(shù)據(jù)
這類API有一個(gè)非常不好的地址，只要業(yè)務(wù)需求變動(dòng)铭若，這個(gè)api就需要跟著變更洪碳。
自定義組合api
把當(dāng)前用戶需要在第一時(shí)間內(nèi)容加載的多個(gè)接口合并成一個(gè)請(qǐng)求發(fā)送到服務(wù)端，服務(wù)端根據(jù)請(qǐng)求內(nèi)容叼屠，一次性把所有數(shù)據(jù)合并返回,相比于頁面級(jí)api瞳腌，具備更高的靈活性，同時(shí)又能很容易的實(shí)現(xiàn)頁面級(jí)的api功能镜雨。
規(guī)范
地址：api/v1/batApi
傳入?yún)?shù)：
data:[
{url:'api1',type:'get',data:{...}},
{url:'api2',type:'get',data:{...}},
{url:'api3',type:'get',data:{...}},
{url:'api4',type:'get',data:{...}}
]返回?cái)?shù)據(jù)
{status:0,msg:'',
data:[
{status:0,msg:'',data:[]},
{status:-1,msg:'',data:{}},
{status:1,msg:'',data:{}},
{status:0,msg:'',data:[]},
]
}
Api共建平臺(tái)
RAP是一個(gè)GUI的WEB接口管理工具嫂侍。在RAP中，您可定義接口的URL荚坞、請(qǐng)求&響應(yīng)細(xì)節(jié)格式等等挑宠。通過分析這些數(shù)據(jù)，RAP提供MOCK服務(wù)颓影、測(cè)試服務(wù)等自動(dòng)化工具各淀。RAP同時(shí)提供大量企業(yè)級(jí)功能，幫助企業(yè)和團(tuán)隊(duì)高效的工作诡挂。
什么是RAP?
在前后端分離的開發(fā)模式下碎浇，我們通常需要定義一份接口文檔來規(guī)范接口的具體信息。如一個(gè)請(qǐng)求的地址璃俗、有幾個(gè)參數(shù)南捂、參數(shù)名稱及類型含義等等。RAP 首先方便團(tuán)隊(duì)錄入旧找、查看和管理這些接口文檔溺健，并通過分析結(jié)構(gòu)化的文檔數(shù)據(jù)，重復(fù)利用并生成自測(cè)數(shù)據(jù)钮蛛、提供自測(cè)控制臺(tái)等等... 大幅度提升開發(fā)效率鞭缭。
RAP的特色
強(qiáng)大的GUI工具 給力的用戶體驗(yàn)，你將會(huì)愛上使用RAP來管理您的API文檔魏颓。
完善的MOCK服務(wù) 文檔定義好的瞬間岭辣，所有接口已經(jīng)準(zhǔn)備就緒。有了MockJS甸饱，無論您的業(yè)務(wù)模型有多復(fù)雜沦童，它都能很好的滿足仑濒。
龐大的用戶群 RAP在阿里巴巴有200多個(gè)大型項(xiàng)目在使用，也有許多著名的公司偷遗、開源人士在使用墩瞳。RAP跟隨這些業(yè)務(wù)的成行而成長(zhǎng)，專注細(xì)節(jié)氏豌，把握質(zhì)量喉酌，經(jīng)得住考驗(yàn)。
免費(fèi) + 專業(yè)的技術(shù)支持 RAP是免費(fèi)的泵喘，而且你的技術(shù)咨詢都將在24小時(shí)內(nèi)得到答復(fù)泪电。大多數(shù)情況，在1小時(shí)內(nèi)會(huì)得到答復(fù)纪铺。
RAP是一個(gè)可視化接口管理工具 通過分析接口結(jié)構(gòu)相速，動(dòng)態(tài)生成模擬數(shù)據(jù)，校驗(yàn)真實(shí)接口正確性鲜锚， 圍繞接口定義和蚪，通過一系列自動(dòng)化工具提升我們的協(xié)作效率。我們的口號(hào)：提高效率烹棉，回家吃晚飯！
