整體規(guī)范建議采用RESTful 方式來實施。
API與用戶的通信協(xié)議，總是使用HTTPs協(xié)議，確保交互數(shù)據(jù)的傳輸安全。
應(yīng)該盡量將API部署在專用域名之下。
如果確定API很簡單，不會有進(jìn)一步擴(kuò)展，可以考慮放在主域名下。
應(yīng)該將API的版本號放入URL。
另一種做法是，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。Github采用這種做法。
采用多版本并存，增量發(fā)布的方式
v{n} n代表版本號,分為整形和浮點(diǎn)型
整形的版本號: 大功能版本發(fā)布形式；具有當(dāng)前版本狀態(tài)下的所有API接口 ,例如：v1,v2
浮點(diǎn)型：為小版本號，只具備補(bǔ)充api的功能，其他api都默認(rèn)調(diào)用對應(yīng)大版本號的api 例如：v1.1 v2.2
路徑又稱'終點(diǎn)'（endpoint），表示API的具體網(wǎng)址。
在RESTful架構(gòu)中，每個網(wǎng)址代表一種資源（resource），所以網(wǎng)址中不能有動詞，只能有名詞，而且所用的名詞往往與數(shù)據(jù)庫的表格名對應(yīng)。一般來說，數(shù)據(jù)庫中的表都是同種記錄的'集合'（collection），所以API中的名詞也應(yīng)該使用復(fù)數(shù)。
舉例來說，有一個API提供動物園（zoo）的信息，還包括各種動物和雇員的信息，則它的路徑應(yīng)該設(shè)計成下面這樣。
對于資源的具體操作類型，由HTTP動詞表示。
常用的HTTP動詞有下面四個（括號里是對應(yīng)的SQL命令）。
GET（SELECT）：從服務(wù)器取出資源（一項或多項）。
POST（CREATE）：在服務(wù)器新建一個資源。
PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。
DELETE（DELETE）：從服務(wù)器刪除資源。
下面是一些例子。
GET /product：列出所有商品
POST /product：新建一個商品
GET /product/ID：獲取某個指定商品的信息
PUT /product/ID：更新某個指定商品的信息
DELETE /product/ID：刪除某個商品
GET /product/ID/purchase ：列出某個指定商品的所有投資者
get /product/ID/purchase/ID：獲取某個指定商品的指定投資者信息
如果記錄數(shù)量很多，服務(wù)器不可能都將它們返回給用戶。API應(yīng)該提供參數(shù)，過濾返回結(jié)果。
下面是一些常見的參數(shù)。
?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數(shù)。
?sortby=name&order=asc：指定返回結(jié)果按照哪個屬性排序，以及排序順序。
?producy_type=1：指定篩選條件
傳入?yún)?shù)分為4種類型：
地址欄參數(shù)
* restful 地址欄參數(shù) /api/v1/product/122 122為產(chǎn)品編號，獲取產(chǎn)品為122的信息
* get方式的查詢字串 見過濾信息小節(jié)
請求body數(shù)據(jù)
cookie
request header
cookie和header 一般都是用于OAuth認(rèn)證的2種途徑
只要api接口成功接到請求，就不能返回200以外的HTTP狀態(tài)。
為了保障前后端的數(shù)據(jù)交互的順暢，建議規(guī)范數(shù)據(jù)的返回，并采用固定的數(shù)據(jù)格式封裝。
接口返回模板：
status: 接口的執(zhí)行的狀態(tài)
=0表示成功
<0 表示有異常=''>
Data 接口的主數(shù)據(jù)
可以根據(jù)實際返回數(shù)組或JSON對象
Msg 信息
當(dāng)status!=0 都應(yīng)該有錯誤信息
由于實際業(yè)務(wù)開展過程中，可能會出現(xiàn)各種的api不是簡單的restful 規(guī)范能實現(xiàn)的，因此，需要有一些api突破restful規(guī)范原則。特別是移動互聯(lián)網(wǎng)的api設(shè)計，更需要有一些特定的api來優(yōu)化數(shù)據(jù)請求的交互。
把當(dāng)前頁面中需要用到的所有數(shù)據(jù)通過一個接口一次性返回全部數(shù)據(jù)
舉例
api/v1/get-home-data 返回首頁用到的所有數(shù)據(jù)
這類API有一個非常不好的地址，只要業(yè)務(wù)需求變動，這個api就需要跟著變更。
把當(dāng)前用戶需要在第一時間內(nèi)容加載的多個接口合并成一個請求發(fā)送到服務(wù)端，服務(wù)端根據(jù)請求內(nèi)容，一次性把所有數(shù)據(jù)合并返回,相比于頁面級api，具備更高的靈活性，同時又能很容易的實現(xiàn)頁面級的api功能。
規(guī)范
地址：api/v1/batApi
傳入?yún)?shù)：
返回數(shù)據(jù)
RAP是一個GUI的WEB接口管理工具。在RAP中，您可定義接口的URL、請求&響應(yīng)細(xì)節(jié)格式等等。通過分析這些數(shù)據(jù)，RAP提供MOCK服務(wù)、測試服務(wù)等自動化工具。RAP同時提供大量企業(yè)級功能，幫助企業(yè)和團(tuán)隊高效的工作。
在前后端分離的開發(fā)模式下，我們通常需要定義一份接口文檔來規(guī)范接口的具體信息。如一個請求的地址、有幾個參數(shù)、參數(shù)名稱及類型含義等等。RAP 首先方便團(tuán)隊錄入、查看和管理這些接口文檔，并通過分析結(jié)構(gòu)化的文檔數(shù)據(jù)，重復(fù)利用并生成自測數(shù)據(jù)、提供自測控制臺等等... 大幅度提升開發(fā)效率。
強(qiáng)大的GUI工具 給力的用戶體驗，你將會愛上使用RAP來管理您的API文檔。
完善的MOCK服務(wù) 文檔定義好的瞬間，所有接口已經(jīng)準(zhǔn)備就緒。有了MockJS，無論您的業(yè)務(wù)模型有多復(fù)雜，它都能很好的滿足。
龐大的用戶群 RAP在阿里巴巴有200多個大型項目在使用，也有許多著名的公司、開源人士在使用。RAP跟隨這些業(yè)務(wù)的成行而成長，專注細(xì)節(jié)，把握質(zhì)量，經(jīng)得住考驗。
免費(fèi) + 專業(yè)的技術(shù)支持 RAP是免費(fèi)的，而且你的技術(shù)咨詢都將在24小時內(nèi)得到答復(fù)。大多數(shù)情況，在1小時內(nèi)會得到答復(fù)。
RAP是一個可視化接口管理工具 通過分析接口結(jié)構(gòu)，動態(tài)生成模擬數(shù)據(jù)，校驗真實接口正確性， 圍繞接口定義，通過一系列自動化工具提升我們的協(xié)作效率。我們的口號：提高效率，回家吃晚飯！
力！
