API接口設計規範

API總體設計規範

協議

API與客戶端通信協議主要包含http和https，建議使用https確保交互數據的傳輸安全。

域名

主要包含兩種形式：

1. 主域名：api.example.com
2. 子目錄：example.org/api/

版本控制

版本控制主要用於App、微信小程序、軟件客戶端等與系統不可同時實時更新的狀況，來知足須要兼容舊版本的場景。 採用多版本並存，增量發佈的方式。

版本號：v{n} n表明版本號,分爲整形和浮點型 整型: 大功能版本發佈形式；具備當前版本狀態下的全部API接口 ,例如：v1,v2 浮點型：爲小版本號，只具有補充api的功能，其餘api都默認調用對應大版本號的api 例如：v1.1 v2.2

1. 將版本號放入URL中： api.example.com/v{n}/ 這種方法比較方便和直觀，版本號主要以整型爲主。

2. 將版本號放在請求頭（Request Headers）中

   headers:{
   	version: 'v{n}'
   	...
   }
   複製代碼

   版本號可以使用整型、浮點型等

路徑規則

路徑又稱"終點"（endpoint），表示API的具體網址。 在RESTful架構中，每一個網址表明一種資源（resource），因此網址中不能有動詞，只能有名詞，並且所用的名詞每每與數據庫的表格名對應。通常來講，數據庫中的表都是同種記錄的"集合"（collection），因此API中的名詞也應該使用複數。 舉例來講，有一個API提供動物園（zoo）的信息，還包括各類動物和僱員的信息，則它的路徑應該設計成下面這樣。

api.example.com/v1/products api.example.com/v1/users api.example.com/v1/employee…

請求方式

對於資源的具體操做類型，由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：獲取某個指定商品的指定投資者信息

傳入參數

傳入參數分爲3中類型

1. 地址欄參數

• restful 地址欄參數 /api/v1/product/122 122爲產品編號，獲取產品爲122的信息
• get方式的查詢字串，此種方式主要用於過濾查詢，以下：

?limit=10：指定返回記錄的數量 ?offset=10：指定返回記錄的開始位置。 ?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。 ?sortby=name&order=asc：指定返回結果按照哪一個屬性排序，以及排序順序。 ?producy_type=1：指定篩選條件

2. 請求body數據

主要用於提交新建數據等

3.請求頭

用於存放請求格式信息、版本號、token密鑰、語言等信息。

{
	Accept: 'application/json',     //json格式
	version: 'v1.0'                       //版本號
	Authorization: 'Bearer {access_token}',   //認證token
	language: 'zh'                      //語言
}
複製代碼

返回格式

默認返回格式：

{
	code: 0,                         //狀態碼
	msg: 'ok',                       //提示信息
	data: {}                          //主體數據
}
複製代碼

使用json格式做爲響應格式，狀態碼分爲兩種：

• statusCode: 系統狀態碼，用於處理響應狀態，與http狀態碼保持一致，如：200表示請求成功，500表示服務器錯誤。
• code：業務狀態碼，用於處理業務狀態，通常0標識正常，可根據需求自行設計錯誤碼對照表，參考

  

非Restful Api的需求

咱們通常以Restful Api做爲接口規範，可是因爲實際業務開展過程當中，可能會出現各類的api不是簡單的restful 規範能實現的，所以，須要有一些api突破restful規範原則。特別是移動互聯網的api設計，更須要有一些特定的api來優化數據請求的交互。

組合型：

服務端組裝數據，而後返回： 把當前頁面中須要用到的全部數據經過一個接口一次性返回所有數據，如：

api/v1/get-home-data 返回首頁用到的全部數據

這類API有一個很是很差的地址，只要業務需求變更，這個api就須要跟着變動。

單例型：

客戶端根據需求分別請求對應Api接口，在客戶端完成組裝。 這種模式服務端相對簡單，接口複用率高。 每一個接口做用單一，如一個App首頁，可能有輪播圖、分類、推薦商品，則須要分別請求：

/api/v1/banners: 輪播 /api/v1/categories: 分類 /api/v1/product?is_recommend=1: 商品

開發過程當中可根據實際須要結合使用。

todo

Laravel中實踐使用。

參考：github.com/mishe/blog/…