BaaS API 設計規範

標籤：

上個月寫了一個團隊中的 BaaS API 的設計規範，給大家分享下：

目錄

1. 引言... 4

1.1. 概要... 4

1.2. 參考資料... 4

1.3. 閱讀對象... 4

1.4. 術語解釋... 4

2. API 設計規範... 5

2.1. 地址格式... 5

2.2. 輸入與輸出... 6

2.2.1. 通用輸入資料... 6

2.2.2. 主體輸入... 6

2.2.3. 通用輸出資料... 6

2.2.4. 狀態代碼... 7

2.2.5. 異常處理... 7

2.2.6. 其它... 8

2.3. API操作設計... 8

2.3.1. 資源型操作... 8

2.3.2. 業務型操作... 12

3. API 協助文檔規範... 12

3.1. 協助文檔內容規範... 12

3.2. 文檔編寫方法... 13

3.3. 協助文檔XML模板... 13

1. 引言 1.1. 概要

BAAS 平台上的所有 API，必須嚴格遵守本規範。

通過本文檔規範 BAAS 平台所有向外提供 API，體現技術的統一性、規範性。並使得所有 API 盡量靠近業界規範的同時，提高API的易用性、可讀性、相容性等，並方便平台的使用者更快地發現、熟悉所有API以供開發。

主要包含兩個方面的規範：API 本身的設計規範、API 協助文檔的編寫規範。

1.2. 參考資料

《Representational State Transfer (REST)》

1.3. 閱讀對象

· 需要把 API 發布到BAAS 平台中的所有開發人員。

· 使用 BAAS API 的開發人員。

1.4. 術語解釋

? BAAS：後端即服務。參見：《BaaS服務的定義、發展以及未來》。

? REST：一種開放的基於互連網的軟體架構模式。參見：《Representational State Transfer (REST)》。

2. API 設計規範 2.1. 地址格式

對於發布的所有 API，地址應該滿足以下格式：

· 格式一，直接存取資源型：

/api/v(version)/area/resources/{id}

· 格式二，資源查詢型：

/api/v(version)/area/resources/param1Name/param1Value/param2Name/param2Value/?optionalParameters

· 格式三，資源操作型、跨資源業務型：

/api/v(version)/area/resources or controller/action?parameters

樣本：

/api/v1.0/acs/users/ 表示訪問所有的使用者資源。

/api/v1.0/acs/users/1 表示訪問 Id 為 1 的使用者。

/api/v1.0/acs/users/group/iws-tech/minAge/30 表示訪問 iws-tech 組中最小年齡30歲的使用者。

/api/v1.0/acs/accounts/UpdateAllUserFlags 表示更新所有使用者的某個標識。

其它說明：

Version 表示版本號碼，只有兩級的版本號碼。

不同的版本號碼之間，原則上可以不保證 API 的相容。

某個版本一旦發布，在同一個版本號碼之內的 api 升級，必須保證相容原來發布的 API。不能相容時，需要使用新的 API 地址，同時必須保留舊的 API。

Area 表示某個業務模組，如 ACS、Org、OneDoc、OnePlus 等。

2.2. 輸入與輸出 2.2.1. 通用輸入資料

對於整個BAAS中每一個 API 的調用都需要提交的資料，使用 Http Header 來進行傳輸。例如：App 授權碼、使用者標識 等資訊。

某個 Area 中大量 API都需要提交的資料，也應該使用 Http Header 來進行提交。

2.2.2. 主體輸入

考慮到介面的擴充性，所有API的輸入只能接受一般的 JSON 對象作為輸入參數，同時也只能輸出一個 JSON 對象。

當輸入輸出的值是單一值、數組時，需要使用一個對象對其進行封裝。

所有 JSON 對象的屬性名稱，全部使用首字母小寫駝峰式文法。

2.2.3. 通用輸出資料

對於 CDU 以及修改資料為主的操作型API的響應，都必須返回一個統一的資料格式 Result，該結構定義如下：

{ success: boolean, statusCode: int, message: string, data: object }

其中：

success：表示該操作是否成功。

statusCode：該操作如果有多種返回的狀態，使用statusCode進行區分。一般情況下，statusCode 返回1或0表示成功或失敗。該屬性用於給開發人員進行程式分支的邏輯判斷使用。

message：總是返回一個可用於用戶端顯示的字串。該屬性用於顯示給軟體使用者查看。

data是可選屬性。即如果沒有額外的資料，可以沒有data屬性，也可以data 返回 null。

2.2.4. 狀態代碼

狀態代碼分為兩類，一個是 Http 狀態代碼；一個是 Result 資料結構中的 StatusCode 狀態代碼。HTTP 狀態代碼表示該 HTTP 要求的處理狀態。一個請求是否成功是由 HTTP 狀態代碼標明的. 一個 2XX 的狀態代碼表示成功, 而一個 4XX 表示請求失敗.

一般情況下，如果能使用 HTTP 狀態代碼表示的狀態，應該優先使用 HTTP 狀態代碼。其次，BAAS 內部的各種商務邏輯狀態，則應該由 StatusCode 來標明。

1. 對於 HTTP 狀態代碼而言，所有API暫時只使用以下狀態代碼：

· 200：操作成功返回。

· 201：表示建立成功，POST 添加資料成功後必須返回此狀態代碼。

· 400：請求格式不對。

· 401：未授權。（App、User）

· 404：請求的地址未找到。如 users/1 未找到該資源。

· 500：內部程式錯誤。

其中，201、404這兩個狀態代碼，是需要API開發人員在每一個API中，根據商務邏輯的執行結果來主動返回的。其它的狀態代碼由架構統一進行返回。

2. StatusCode

StatusCode將統一使用6位編碼，代表所有不同的商務邏輯分支。6位編碼中的前兩位代表不同的Area （模組），由BAAS平台統一規範。後四位由模組開發人員自行定義。如：01表示ACS，那麼010001可能表示ACS模組中的登入API的使用者名稱錯誤、010002表示ACS中的登入API的使用者密碼錯誤。

2.2.5. 異常處理

請求失敗返回 4XX 後，響應的主體依然是 Result 資料格式。其中 message 表示錯誤的資訊。方便進行調試。如：

HttpStatusCode:404

Response Body:{success:false, statusCode:100003, message:‘不存在該使用者。‘}

2.2.6. 其它

時間的格式：API返回 值中的時間，都統一採用UTC格式 時間。

API的傳回值中，如果需要包含調試相關資訊（如調用時間、調用次數等），由BAAS平台架構統一處理，不單獨在各API中處理。

2.3. API操作設計

每個具體的 API地址，都是一個操作。操作分為兩種類型：資源型操作、業務型操作。

2.3.1. 資源型操作

資源型操作是滿足REST正常化設計的。在設計API 時，應盡量首選這種模式。即：如果 API 能抽象為資源的CRUD操作的，應該盡量先抽象為對資源的操作。

2.3.1.1. 添加

地址：資源清單地址。如 /users/。

使用 POST動作提交實體對應的JSON格式資料。

2.3.1.2. 更新

地址：具體某個資源的地址。如 /users/1，表示id為1的使用者。

動作：使用 PUT 動作提交。

資料格式：實體的 JSON格式資料。其中，JSON 資料中不需要列全所有的屬性，只需要列出需要更新的屬性即可。

如：PUT /users/1 {username:‘hqf‘}。

對應的響應是：

HttpStatusCode:200

ResponseBody： { success: true, statusCode: 1, message: ‘更新成功！‘}

（另：如果使用 ASP.NET WebApi 架構搭建API，則這裡需要提供統一的架構處理此類型的還原序列化。）

2.3.1.3. 刪除

地址：具體某個資源的地址。如 /users/1。

動作：使用DELETE動作提供請求。

如：DELETE /users/1

對應的響應是：

HttpStatusCode:200

ResponseBody： { success: true, statusCode: 1, message: ‘刪除成功！‘}

2.3.1.4. 批量儲存

設計建議：盡量不要為每一個資源提供批量儲存的操作。只有在對資源的操作的效能要求較高時，才選擇性提供。

地址：資源清單地址。如 /users/。

動作：使用 POST 動作提供資料。

資料格式：使用一個 JSON 對象提交資料，該對象中包含一個屬性名稱為 list，屬性類型為數組的屬性。該數組中的每一個對象都是要更新的實體物件。

對於每一個實體物件：可以為每一個子實體物件添加 persistenceStatus 屬性，值為 Deleted、Modified、New 來表示該實體的狀態：刪除、更新、添加。如果不提供該屬性，那麼如果實體有 Id 屬性，則表示更新，否則表示添加。

例如：

{list:[

{name:‘c1‘, persistenceStatus:‘New‘},

{id:1, name:‘c2‘, persistenceStatus:‘Modified‘},

{id:2, persistenceStatus:‘Deleted‘}

]}

也可省略為：

{list:[

{name:‘c1‘},//添加

{id:1, name:‘c2‘},//更新

{id:2, persistenceStatus:‘Deleted‘}

]}

2.3.1.5. 儲存彙總子

設計建議：在需要更新彙總子實體時，如果公布了彙總子資源 API，那麼應該首選這個資源來實現儲存。否則，才可以在更新彙總父實體時，同時更新它的彙總子實體。

地址與動作：儲存彙總子使用彙總父資源相同的地址和動作，見：更新。

資料格式：彙總父物件中有彙總子對應的屬性，該屬性使用批次更新中定義的資料格式來定義需要更新的彙總子實體集合。見：批量儲存。如：

{name:‘parent‘, children:[

{name:‘c1‘, persistenceStatus:‘New‘},

{id:1, name:‘c2‘, persistenceStatus:‘Modified‘},

{id:2, persistenceStatus:‘Deleted‘}

]}

也可省略為：

{name:‘parent‘, children:[

{name:‘c1‘},

{id:1, name:‘c2‘},

{id:2, persistenceStatus:‘Deleted‘}

]}

2.3.1.6. 查詢 · 查詢所有資源

地址：資源清單地址。如：/users/。

動作：使用 GET 來進行請求。

· 查詢指定id的資源

地址：資源地址+Id。如：/users/1。

動作：使用 GET 來進行請求。

· 其它查詢

每一個特殊查詢，都需要提供相應的特殊查詢地址。必須參數以URI Part 的形式給出，選擇性參數則以查詢字串的形式給出。例如，使用以下格式：

/users/username/hqf/minAge/30/?optionalParam1=1

如果兩個 API 使用了相同的參數，則需要在資源後追加一個查詢的名稱，用以區分。如：

/users/find2/username/hqf/minAge/30/?optionalParam1=1

· OData 查詢

設計建議：盡量不要提供OData查詢。

如果要提供OData查詢API，必須考慮查詢的許可權的限制，同時不要公布排序介面，否則效能可能會很差。

· 查詢資源的合集

有時，查詢不是直接針對某個單一的資源，而是聯集查詢一系列資源的合集，傳回值的格式也與單一資源格式不同。這時，需要為這個資源合集聲明一個新的資源地址。例如，查詢使用者與角色的合集，可以使用新的資源地址：/userRoles/。

2.3.2. 業務型操作

業務型動作表示可能跨越多個資源的邏輯操作。伺服器端直接提供的服務。

· 一般只使用 POST 動作，偶爾使用 GET 動作。不能使用 PUT、DELETE 動作。

· Action 不要使用簡單的、通用的名稱。如不要使用與資源操作衝突的 Get、Add、Update、Delete、Save 等名稱。而使用具體的邏輯名稱，如 transfer、refreshTag 等……

· 推薦放到單獨的服務地址（控制器）中。如：POST /{transaction}/{transfer} {from:‘a‘,to:‘b‘,money:10}。

· 如果只是對某個資源單獨的操作，那麼也可以放在該資源地址下。如：POST /users/refreshLogoutTime。;

3. API 協助文檔規範

BAAS 平台中的 API 協助文檔將採用統一的格式編寫，並以 HTML 頁面的形式發布。

協助文檔使用以下地址：GET /api/v1.1/ 返回 1.1 版本 API 的協助文檔首頁。

3.1. 協助文檔內容規範

向外公布的每個API的協助說明，必須至少包含以下幾項：

· API 簡介

· 請求

o 說明請求的方法、地址。

o URI 參數：如果 URI 中某部分是動態，請使用大括弧說明：api/values/{id}。

o URI 查詢參數：如果 URI 地址有參數，描述各項參數與說明。每個參數是否可選。

o 請求標題：如果有特殊的請求標題，需要特別逐一說明。

· 響應

o 說明響應的狀態代碼、內容格式。

o 響應標題：如果有特殊的請求標題，需要特別逐一說明。

o 響應本文：特殊欄位、重點必須說明含義。盡量說明響應本文的所有欄位意義。

· 可選：授權、備忘

· 樣本請求與響應

參考樣本：

· MS Azure 文檔樣本

3.2. 文檔編寫方法

API開發人員需要為其公布的每一個 API建立一個XML文檔用於詳細描述上述的協助內容。該文檔建議以與API對應的方法名起名，方便尋找。文檔的內容由統一的模板確定。

架構組提供統一的轉換工具來產生相應的 API 網頁。最終會整合在整個 API 網站中。

3.3. 協助文檔XML模板

該模板以附件形式給出。

 

檔案：http://pan.baidu.com/s/1pJsswQJ

BaaS API 設計規範