相關文章：
整體規範建議採用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是一個可視化接口管理工具 通過分析接口結構，動態生成模擬數據，校驗真實接口正確性， 圍繞接口定義，通過一系列自動化工具提升我們的協作效率。我們的口號：提高效率，回家吃晚飯！
文章來源：http://mp.weixin.qq.com/s/OhN5yysTkfScsWJB2Y2lrQ