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 本文版權歸做者和博客園共有，歡迎轉載， 但未經做者贊成必須保留此段聲明， 且在文章頁面明顯位置給出原文鏈接。