API 介面設計規範

franktrue發表於2019-01-29
API

協議

API與客戶端通訊協議主要包含http和https，建議使用https確保互動資料的傳輸安全。

域名

主要包含兩種形式：

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

版本控制

版本控制主要用於App、微信小程式、軟體客戶端等與系統不可同時實時更新的情況，來滿足需要相容舊版本的場景。
採用多版本並存，增量釋出的方式。

版本號：v{n} n代表版本號,分為整形和浮點型
整型: 大功能版本釋出形式；具有當前版本狀態下的所有API介面 ,例如：v1,v2
浮點型：為小版本號，只具備補充api的功能，其他api都預設呼叫對應大版本號的api 例如：v1.1 v2.2

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

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

    headers:{
    version: 'v{n}'
    ...
}

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

路徑規則

路徑又稱"終點"（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動詞有下面四個（括號裡是對應的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標識正常，可根據需求自行設計錯誤碼對照表，參考
    file

非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: 商品

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

Laravel中實踐使用。

參考：https://github.com/mishe/blog/issues/129

本作品採用《CC 協議》，轉載必須註明作者和本文連結

相關文章