API說明書規范

   

目錄

1       前言

1.1         編寫目的

1.2         預期讀者

1.3         關於API設計開發

2       API公共說明

3       文檔API索引

4       單個API說明

4.1         API基本信息

4.2         API輸入參數

4.2.1          參數分類

4.2.2          參數類型

4.2.3          參數說明表格

4.3         API響應結果

4.3.1          API響應結果說明示例

4.4         API附錄

 

 

1    前言

1.1   編寫目的

信息系統不可避免會與三方系統產生交互，本文將會定義信息系統體系下所有接口文檔的一些通用約定。

API設計開發完成后，在保證API完整性和穩定性的情況下，需要對API接口進行詳細的說明，本文檔將約定如何對API接口進行說明。

注：本文檔中所提及接口，都是信息系統對外提供的接口，接口作為被調用方，而不是指三方系統需要ERP去調用的接口。

1.2   預期讀者

• 系統接口設計開發人員
• 系統接口使用人員
• 系統三方對接公司

1.3   關於API設計開發

為信息系統開發的API需要仔細考慮，API地址名稱、API輸入參數、API返回值都應經過嚴格推敲，API是提供外部三方調用，需要經過嚴格測試，特別是對於會修改系統數據的API要有嚴格的參數驗證和安全性驗證。

API開發設計相關主題，不在本文檔討論范圍內，具體請閱讀《API設計開發規范》。

 

2    API公共說明

API公共說明需要明確API相關公共屬性，包含但不局限於以下表格內容。

API集名稱	例如：庫房管理系統接口（Warehouse Management System API）
API集說明	例如：圍繞半成品立體倉庫，提供庫房相關商品信息、商品數量信息、商品庫位信息的查詢，提供庫房相關盤點信息的提交，提供入庫出庫等操作的執行。
API基地址	API所在IP或域名 例如 api.huaisheng.wang
支持協議	Http、Https或其它支持的協議
API基本結構	應對API中支持的輸入或相應數據結構進行規約，並提供詳細的說明。 例如：所有API不管成功或錯誤，HttpStatus狀態碼都返回200。 具體的執行結果 {     "return_code": "0",     "message": "",     "success": true     "result": {         "page_index": 2,         "total_count": 52,         "page_count":20,         "rows": list<T>     } } 其中return_code在不為0時，代表錯誤碼，可以據此排查錯誤字典，獲取錯誤具體類型。 message在success=true時為空，否則為錯誤碼對應的錯誤描述 success為true代表成功，為false代表出現異常 result為成功時的結果信息，success=false時為空
鑒權說明	需要對API的鑒權方式進行詳細說明。 例如： API必須包含鑒權參數appkey、userid、timestamp和sign，這4個參數是所有接口都必須有的，服務后端會使用保存的appsecret對sign進行驗證，timestamp有效時間20s，userid為登錄用戶名。鑒權參數需要以請求參數的方式提供，不能放入RequestBody中。
API規約	應對API命名、入參、響應結果、字段名稱、對象定義等進行規約，並在公共說明中體現。 例如： API命名必須體現API的實際意義，一目了然，通過名稱就可以基本確定API的作用，命名采用完整英文單詞，多個單詞用下划線分隔，名稱不區分大小寫。例如get_employee_list、get_user …………

3    文檔API索引

盡可能提供所有支持的API列表，API列表項點擊后跳轉到對應的API說明，列表格式參考以下表格。

API地址	API中文名	API說明
api/values/getvalues	獲取XXXX值

4    單個API說明

API文檔需要對每一個對外提供的接口進行詳細的說明，詳細說明至少包含API基本信息、API輸入參數、API響應結果、API中涉及到的所有對象、枚舉等內容。

4.1   API基本信息

API類別	獲取數據、變更數據
Http請求方法	GET、POST、PUT、DELETE等
API地址	不包含基地址的Api訪問地址，在使用時結合協議、API基地址才成為真實的API調用地址 例如： 協議“https”，基地址“api.huaisheng.wang”， API地址“api/orders/getlist?kind={kind}” 組合后的真實訪問地址為： https://api.huaisheng.wang/api/orders/getlist?kind=1
API說明	對API的中文說明信息 例如：上面單元格API地址對應“獲取類型為1的訂單列表”。

4.2   API輸入參數

4.2.1  參數分類

API參數分為三種：URL路徑參數、URL查詢參數、請求體參數。
URL路徑參數	URL Path Parameter 比如api/orders/getlist/{sealerid}?orderkind={orderkind} 其中的{sealerid}就是路徑參數 對應具體的請求api/orders/getlist/1?orderkind=2 路徑參數sealerid=1 查詢參數orderkind=2
URL查詢參數	URL Query Parameter 比如/api/test?a=1&b=2，其中a和b就是查詢參數
請求體參數	Request Body Parameter 調用方需要將參數按給的的格式構造在請求的body里面，發送到對應的API地址。在我們提供的API中，通常情況下請求體參數為JSON格式（API的Content-Type為application/json）。

4.2.2  參數類型

API說明書需要對入參的參數類型進行詳細的說明。

例如：

API支持所有參數類型如下表格所示：

參數類型

說明

string

字符串類型

Integer

整型

long

長整型

float

浮點型

boolean

布爾型

對象

Object

例如：

TestPerson

 

需要對對象所有屬性進行說明，說明格式如下表格所示

屬性名	中文名	類型	備注
Name	姓名	String
Age	年齡	Integer

 

對象集合

Collection of Object

例如：

Collection of TestPerson

需要對對象所有屬性進行說明，說明格式如下表格所示

屬性名	中文名	類型	備注
name	姓名	string
age	年齡	integer

其它

依據實際情況添加相關說明。

比如對最常返回的對象進行特殊說明

4.2.3  參數說明表格

每個API需要對參數進行表格化說明，包含參數、名稱、類型、是否必須、備注，表格格式如下：

參數	名稱	類型	必須	備注
age	年齡	integer	Yes

4.3    API響應結果

需要對API響應結果進行詳細說明，包含響應數據類型，響應Http狀態碼，響應詳細格式及說明等。在API說明文檔中需要對響應內容給出示例。

4.3.1  API響應結果說明示例

API支持json和xml兩種格式，會依據請求客戶端的需要返回對應類型的數據。

JSON格式

Mime類型：APPLICATION/JSON,TEXT/JSON

Sample:

{

  "return_code": 1,

  "success": true,

  "message": "sample string 2",

  "result": [

    {

      "Name": "sample string 1",

      "Age": 2

    },

    {

      "Name": "sample string 1",

      "Age": 2

    }

  ]

}

XML格式

Mime類型：APPLICATION/XML,TEXT/XML

Sample:

<ArrayOfTestPerson xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Models.Dto.Posts">

  <Message>sample string 2</Message>

  <Result xmlns:d2p1="http://schemas.datacontract.org/2004/07/Models.Dto.Tests">

    <d2p1:TestPerson>

      <d2p1:Age>2</d2p1:Age>

      <d2p1:Name>sample string 1</d2p1:Name>

    </d2p1:TestPerson>

    <d2p1:TestPerson>

      <d2p1:Age>2</d2p1:Age>

      <d2p1:Name>sample string 1</d2p1:Name>

    </d2p1:TestPerson>

  </Result>

  <ReturnCode>1</ReturnCode>

</ArrayOfTestPerson>

4.4   API附錄

如果接口中使用到一些特定的對象或數據，需要進行額外的說明，這時需要為API添加附錄節（例如API接口的入參或者返回值是有固定的取值枚舉時，一般需要在附錄里面列出具體的枚舉值）。

例如：接口返回人員信息中包含人員類型枚舉

人員類型枚舉
名稱	中文	值	備注
Manager	管理人員	1
OfficialStaff	正式員工	2
TempStaff	臨時員工	3
……

 

 

---

文章作者：花生（OutMan） 發布地址：http://www.cnblogs.com/WangHuaiSheng/  發布時間：2018-04-25 本文版權歸作者和博客園共有，歡迎轉載， 但未經作者同意必須保留此段聲明， 且在文章頁面明顯位置給出原文連接。