導讀
- 背景
- 痛點在哪?
- 為什么要寫接口文檔？
- API規范
- 接口工具
- 總結
背景
隨着業務的發展,支撐組的項目也是越來越多。同時,從整個支撐組項目架構體系(含運維和運營體系),我們對系統業務水平拆分,垂直分層,讓業務系統更加清晰,產生了一系列平台和子系統,並使用接口進行數據交互。伴隨着業務的發展,接口營運而生,並且會越來越多。
痛點在哪
我們運營和維護着諸多的對外接口,很多現有的接口服務寄宿在各個不同的項目,哪些應用在使用api也沒有管理起來。並且以前的調用模式也是比較復雜,排錯困難。
工作中也有合作開發的同事多次強力要求給出api文檔,特別是每個開發組都來要一次,往往解釋半天,大家也很痛苦。那么,讓不開的問題是,如何管理和維護這些api,才能讓大家都輕松?
- 沒有接口文檔
- 接口在代碼里,只能看代碼
- 沒有集中的的api項目
- 相同業務的api分散在不同的項目
- 查找困難
- 代碼和文檔不匹配
- 代碼接口更新,文檔不更新
- 文檔不規范
- 有的是word,有的是excel,有的是txt等等
- api不規范
- 命名,參數不規范
擼碼一分鍾,對接三小時
為什么要寫接口文檔？
- 項目開發過程中服務端和客戶端工程師有一個統一的文件進行溝通交流開發
- 項目維護中或者項目人員更迭,方便后期人員查看、維護
API規范
-
接口名稱
- 這里統一使用小寫 如:api/order/get
- 可參考跟着Github學習Restful HTTP API 設計
-
uri
- 提供客戶端使用的全路徑
- 如http://172.16.0.194:8057/api/order/get
-
請求協議
- Http,Https
-
請求方式
- POST,GET等
-
頭部(系統參數)
- 加密簽名,時間戳等
-
請求參數(業務)
- 業務相關的輸入參數
-
響應參數(業務)
- 輸出參數
-
返回示例
定義返貨結果數據結構,更直觀
- 1.返回成功
- 2.返回失敗
接口工具
-
eolinker
- 以后都使用該工具作為api歸檔
-
目前已經歸檔的項目
-
目前已經歸檔的項目api
總結
項目中使用restfulapi的情況較多,webservice,wcf,webapi均支持，所以這里該規范重點針對resfulapi。
有了規范更能減少溝通誤差,提高工作效率