api介面設計

2021-07-26 06:21:09 字數 2635 閱讀 8894

請求模式也可以說是動作、資料傳輸方式,通常我們在web中的form有get、post兩種,而在http中,存在下發這幾種。

get (選擇):從伺服器上獲取乙個具體的資源或者乙個資源列表。 

post (建立): 在伺服器上建立乙個新的資源。

put(更新):以整體的方式更新伺服器上的乙個資源。 

patch (更新):只更新伺服器上乙個資源的乙個屬性。

delete(刪除):刪除伺服器上的乙個資源。 

head : 獲取乙個資源的元資料,如資料的雜湊值或最後的更新時間。

options:獲取客戶端能對資源做什麼操作的資訊。

offset=10指定返回記錄的開始位置。

page=2&per_page=100指定第幾頁,以及每頁的記錄數。

sortby=name&order=asc指定返回結果按照哪個屬性排序,以及排序順序。

animal_type_id=1指定篩選條件

按照restful的規範,不同的版本也應該用相同的api url,通過header資訊來判斷版本,再呼叫不同版本的程式進行處理。但是這明顯會給開發帶來巨大的成本。

解決辦法有以下幾種:

1.新版本相容舊版本,所有舊版本的動作、字段、操作,都在新版本中可以被實現,但明顯這樣的維護成本很大;

2.不同的版本,用不同的url來提供服務,在url中通過v1、v2來區分版本號,比如v2.api.***.com/user的方式,或者

3.每個介面有各自的版本,一般為介面新增個version的引數。

介面的資料一般都採用json格式進行傳輸,不過,需要注意的是,json的值只有六種資料型別:

所以,傳輸的資料型別不能超過這六種資料型別。以前,我們曾經試過傳輸date型別,它會轉為類似於"2023年1月7日 09時17分42秒 gmt+08:00"這樣的字串,這在轉換時會產生問題,不同的解析庫解析方式可能不同,有的可能會轉亂,有的可能直接異常了。要避免出錯,必須做特殊處理,自己手動去做解析。為了**這種問題,最好的解決方案是用毫秒數或者字串表示日期。

伺服器返回的資料結構,一般為:

}

不同錯誤需要定義不同的返回碼,屬於客戶端的錯誤和服務端的錯誤也要區分,比如1xx表示客戶端的錯誤,2xx表示服務端的錯誤。這裡舉幾個例子:

data欄位只在請求成功時才會有資料返回的。資料型別限定為物件或陣列,當請求需要的資料為單個物件時則傳回物件,當請求需要的資料是列表時,則為某個物件的陣列。這裡需要注意的就是,不要將data傳入字串或數字,即使請求需要的資料只有乙個,比如token,那返回的data應該為:

//

正確data:

//錯誤

data:

123456

其次,即使使用https,也要在api資料傳輸設計時,正確的採用加密。例如直接將token資訊放在url中的做法,即使你使用了https,黑客抓不到你具體傳輸的資料,但是可以抓到你請求的url啊!(查了資料了,https用get方式請求,也僅能抓到網域名稱字元部分,不能抓到請求的資料,但是url可以在瀏覽器或特殊客戶端工具中直接看到。多謝下面的朋友指正錯誤)因此,使用https進行請求時,要採用post、put或者head的方式傳輸必要的資料。

使用者用密碼登入成功後,伺服器返回token給客戶端;

客戶端將token儲存在本地,發起後續的相關請求時,將token發回給伺服器;

伺服器檢查token的有效性,有效則返回資料,若無效,分兩種情況:

然而,此種驗證方式存在乙個安全性問題:當登入介面被劫持時,黑客就獲取到了使用者密碼和token,後續則可以對該使用者做任何事情了。使用者只有修改密碼才能奪回控制權。

我們目前的做法是給每個介面都新增簽名。給客戶端分配乙個金鑰,每次請求介面時,將金鑰和所有引數組合成源串,根據簽名演算法生成簽名值,傳送請求時將簽名一起傳送給伺服器驗證。類似的實現可參考oauth1.0的簽名演算法。這樣,黑客不知道金鑰,不知道簽名演算法,就算攔截到登入介面,後續請求也無法成功操作。不過,因為簽名演算法比較麻煩,而且容易出錯,只適合對內的介面。如果你們的介面屬於開放的api,則不太適合這種簽名認證的方式了,建議還是使用oauth2.0的認證機制。

不需要註冊,不需要修改密碼,也不需要因為忘記密碼而重置密碼的操作了;

使用者不再需要記住密碼了,也不怕密碼洩露的問題了;

相對於密碼登入其安全性明顯提高了。

顯式使用者和隱式使用者,我不知道這兩個詞用的是否確切。 

通常顯式使用者都需要註冊,登入以後能完成一些個人相關的操作。

在這種情況下,可以通過客戶端生成的udid來標識乙個使用者。

有了使用者資訊,我們就能夠了解不同使用者的使用習慣,而不僅僅是全體使用者的乙個整體的統計資訊,

有了這些個體的資訊之後,就可以做一些使用者分群、個性化推薦之類的事情。

如果是saas版本,還需要區分不同商戶的使用者

介面文件有時候是專案初期就定下來的,前後端開發人員按照介面規範開發,

有的是介面開發完成後寫的。

介面文件要清晰、明了,包含多少個介面,每個介面的位址、引數、請求方式、資料交換格式、返回值等都要寫清楚。

介面測試程式,有條件的話,也可以提供,方便前後端的除錯。

如果是springmvc開發的話,可以用swagger,後端只要加幾個注釋發乙個url給前端就可以了,輕鬆又高效。

API介面設計

請求模式也可以說是動作 資料傳輸方式,通常我們在web中的form有get post兩種,而在http中,存在下發這幾種。get 選擇 從伺服器上獲取乙個具體的資源或者乙個資源列表。post 建立 在伺服器上建立乙個新的資源。put 更新 以整體的方式更新伺服器上的乙個資源。patch 更新 只更新...

API介面設計

目前 基本都是前後端分離的模式,如果前端使用vue等框架會產生跨域的問題,當產生跨域的時候,乙個介面會被訪問兩次,第一次會使用options訪問來判斷介面是否通,接下來才會使用指定的請求方式來訪問,那麼這樣怎麼辦呢?我們的共有controller就派上用場了,共有控制器裡面的建構函式 public ...

API介面設計

總結一下api介面開發過程中的注意事項 所謂跨平台是指我們的介面要能夠支援不同的終端,比如android ios windowsphone以及桌面軟體 等。如 不同的終端每頁顯示的記錄數不同 採用通用的解決方案,比如通訊協議就採用最常用的http rpc協議,如果是即時通訊,可以採用開放的xmpp協...