restful api 的設計規範
restful 介面規範
整體規範建議採用restful 方式來實施。
協議api與使用者的通訊協議，總是使用https協議，確保互動資料的傳輸安全。
網域名稱應該盡量將api部署在專用網域名稱之下。
如果確定api很簡單，不會有進一步擴充套件，可以考慮放在主網域名稱下。
api版本控制
應該將api的版本號放入url。
/v/另一種做法是，將版本號放在http頭資訊中，但不如放入url方便和直觀。github採用這種做法。
採用多版本並存，增量發布的方式
v n代表版本號,分為整形和浮點型
整形的版本號: 大功能版本發布形式；具有當前版本狀態下的所有api介面 ,例如：v1,v2
浮點型：為小版本號，只具備補充api的功能，其他api都預設呼叫對應大版本號的api 例如：v1.1 v2.2
api 路徑規則
路徑又稱"終點"（endpoint），表示api的具體**。
在restful架構中，每個**代表一種資源（resource），所以**中不能有動詞，只能有名詞，而且所用的名詞往往與資料庫的**名對應。一般來說，資料庫中的表都是同種記錄的"集合"（collection），所以api中的名詞也應該使用複數。
舉例來說，有乙個api提供動物園（zoo）的資訊，還包括各種動物和雇員的資訊，則它的路徑應該設計成下面這樣。
/v1/products
/v1/users
/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狀態。
為了保障前後端的資料互動的順暢，建議規範資料的返回，並採用固定的資料格式封裝。
介面返回模板：
||,
msg:』』
}
=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功能。
規範傳入引數：
data:[
},},},}
]
,
},},,]
}
rap是乙個gui的web介面管理工具。在rap中，您可定義介面的url、請求&響應細節格式等等。通過分析這些資料，rap提供mock服務、測試服務等自動化工具。rap同時提供大量企業級功能，幫助企業和團隊高效的工作。
什麼是rap?
在前後端分離的開發模式下，我們通常需要定義乙份介面文件來規範介面的具體資訊。如乙個請求的位址、有幾個引數、引數名稱及型別含義等等。rap 首先方便團隊錄入、檢視和管理這些介面文件，並通過分析結構化的文件資料，重複利用並生成自測資料、提供自測控制台等等... 大幅度提公升開發效率。
rap的特色
強大的gui工具 給力的使用者體驗，你將會愛上使用rap來管理您的api文件。
完善的mock服務 文件定義好的瞬間，所有介面已經準備就緒。有了mockjs，無論您的業務模型有多複雜，它都能很好的滿足。
龐大的使用者群 rap在阿里巴巴有200多個大型專案在使用，也有許多著名的公司、開源人士在使用。rap跟隨這些業務的成行而成長，專注細節，把握質量，經得住考驗。
免費 + 專業的技術支援 rap是免費的，而且你的技術諮詢都將在24小時內得到答覆。大多數情況，在1小時內會得到答覆。
rap是乙個視覺化介面管理工具 通過分析介面結構，動態生成模擬資料，校驗真實介面正確性， 圍繞介面定義，通過一系列自動化工具提公升我們的協作效率。我們的口號：提高效率，回家吃晚飯！
RESTful api介面規範
整體規範建議採用restful 方式來實施。協議api與使用者的通訊協議，總是使用https協議，確保互動資料的傳輸安全。網域名稱應該盡量將api部署在專用網域名稱之下。如果確定api很簡單，不會有進一步擴充套件，可以考慮放在主網域名稱下。api版本控制 應該將api的版本號放入url。v 另一種做...
Restful Api介面規範
用名詞代替動詞表示資源 get employees get employees?state external post employees put employees 56 對可選的 複雜的引數，使用查詢字串 get employees?state internal maturity senior ...
RestFul API介面規範
整體規範建議採用restful 方式來實施 協議 api與使用者的通訊協議，總是使用https協議，確保互動資料的傳輸安全。網域名稱 應該盡量將api部署在專用網域名稱之下。如果確定api很簡單，不會有進一步擴充套件，可以考慮放在主網域名稱下。api版本控制 應該將api的版本號放入url。v 另一...