API接口設計要考慮的因素

1、接口版本化

生產環境中,若是沒有版本控制的程序變動會致使調用接口的相關方頻繁的跟着變動,假設相關方沒有及時的跟着變動,那麼系統就會報錯,從而影響到用戶的使用及體驗,使其對整個系統的運營都是不利的,接口對接的難度也會不斷的加大。前端

若是接口可以有版本的控制,則升級系統的主動權就掌握在相關方,這樣當有新版本的程序發佈時舊版本的業務邏輯不會受到影響,從用戶感知上也受到的影響就比較小,相關方也能夠根據自身的條件是否要升級版本。程序員

2、接口面向的應用場景

在對接口進行設計時,咱們還要考慮接口是面向web前端開發仍是手機app開發,或者服務端開發。不一樣的應用場景接口整體規劃是不一樣的(例如:當咱們的接口是提供給web前端或APP端使用時,接口安全驗證咱們能夠採用jwt、oauth2.0等,若是咱們的接口是提供給後端服務使用時,那麼我能夠採用token機制)。web

3、請求參數的規範性及處理的統一性

請求參數的規範性意思就是說,接口要以什麼樣的方式來接收參數。是統一使用json的方式接收呢仍是xml或者form表單方式接收。json

在開發接口應該統一在一個地方進行對參數的接收、校驗等操做。爲了保證參數的完整性,咱們能夠考慮新增簽名驗證等處理。後端

4、返回數據類型、返回碼及信息提示的規範性

返回給客戶端的數據類型應該要統一化(例如:咱們統一以json的形式進行返回,或者是統一以xml的形式返回)。設計模式

不一樣的接口設計模式返回碼也會不一樣,若是使用如今很是火也比較流行的restfull風格那麼就應該要准許restfull風格的返回碼規定。若是是統一採用自定返回碼的話在設計返回碼時,應該要學會針對不一樣的業務處理模塊對返回碼進行分段處理(例如:系統基礎管理咱們使用10000-10050,用戶管理則就應該要從10051到10100,……),針對不一樣業務模塊咱們要預留足夠的返回碼,由於後期針對該模塊的開發可能還會有其它業務的擴展或者調整等問題。返回碼分段處理的一個好處就是方便調用接口的相關方可以很快的定位到錯誤是屬於哪個部分,同時也方便接口開發人員定位接口錯誤在哪一個地方。安全

除了返回碼,咱們對接口返回的錯誤提示信息和接口調用成功的提示信息都應該明確,提示到點上。固然有些錯誤信息多是自身API的bug或者服務器的問題等因素,這樣的話咱們就應該要轉化一下提示不能把API自身問題暴露給接口調用相關方,這樣會致使接口的安全性等問題。服務器

5、接口安全驗證及權限的控制

接口並非每一個操做者都能請求訪問的,因此咱們要爲接口提供一個安全驗證,就像用戶登陸系統同樣,沒有在咱們系統註冊的合法用戶咱們是不容許請求訪問的。那麼咱們要如何對接口進行安全驗證呢?其實針對不一樣的應用場景咱們的接口安全驗證也不同(例如:當咱們的接口是提供給web前端或APP端使用時,接口安全驗證咱們能夠採用jwt、oauth2.0等,若是咱們的接口是提供給後端服務使用時,那麼我能夠採用token機制)。微信

權限的控制是指針對不一樣的用戶羣體,咱們要分配不一樣的權限(例如:超級管理員能夠操做全部接口,普通用戶只容許操做部分接口),這裏除了針對用戶羣體咱們能夠針對不一樣的調用接口的相關方(這裏的相關方是指調用接口的應用)進行權限控制。restful

6、接口調用頻率的控制

對接口的調用頻率進行控制從另外一方面來說也是爲了接口的安全性及接口的可維護性,固然這裏是否要對接口訪問次數進行控制仍是取決於接口針對不一樣的應用場景,有些接口的設計是不須要限制調用頻率的,而有些接口則對接口調用是要進行嚴格控制的(例如:你們熟知的微信公衆號的開發就是對接口的調用頻率進行限制,而且針對不一樣的場景及用戶羣體限制的頻率也不同)。

7、請求接口日誌的記錄

咱們應該要爲接口請求作一下日誌的記錄,這樣咱們後期維護接口時則會大大下降維護成本。並且還能夠針對日誌進行相關的統計處理。

8、接口文檔的可讀性

接口文檔的可讀性很是重要,一個接口開發出來並非真正的完成,若是別人不會使用你的接口,那麼你的接口開發出來也是沒有用的,好多程序員很是的不重視接口文檔撰寫及接口文檔可讀性,寫出來的文檔就像一本天書看着就頭大。好的文檔應該讓人一看就知道如何調用,如何規避一些坑,簡單明瞭等等。這裏我介紹兩個比較好的接口管理可視化工具給你們參考一下swagger和阿里巴巴的rap。

相關文章
相關標籤/搜索