API 接口規範

總體規範建議採用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是一個可視化接口管理工具 經過分析接口結構，動態生成模擬數據，校驗真實接口正確性， 圍繞接口定義，經過一系列自動化工具提高咱們的協做效率。咱們的口號：提升效率，回家吃晚飯！