整體規範建議採用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同時提供大量企業級功能，幫助企業和團隊高效的工作。

什麼是RAP?

在前後端分離的開發模式下，我們通常需要定義一份介面文件來規範介面的具體資訊。如一個請求的地址、有幾個引數、引數名稱及型別含義等等。RAP 首先方便團隊錄入、檢視和管理這些介面文件，並通過分析結構化的文件資料，重複利用並生成自測資料、提供自測控制檯等等... 大幅度提升開發效率。

RAP的特色

強大的GUI工具 給力的使用者體驗，你將會愛上使用RAP來管理您的API文件。

完善的MOCK服務 文件定義好的瞬間，所有介面已經準備就緒。有了MockJS，無論您的業務模型有多複雜，它都能很好的滿足。

龐大的使用者群 RAP在阿里巴巴有200多個大型專案在使用，也有許多著名的公司、開源人士在使用。RAP跟隨這些業務的成行而成長，專注細節，把握質量，經得住考驗。

免費 + 專業的技術支援 RAP是免費的，而且你的技術諮詢都將在24小時內得到答覆。大多數情況，在1小時內會得到答覆。

RAP是一個視覺化介面管理工具 通過分析介面結構，動態生成模擬資料，校驗真實介面正確性， 圍繞介面定義，通過一系列自動化工具提升我們的協作效率。我們的口號：提高效率，回家吃晚飯！