Web API接口設計經(jīng)驗總結

　　Web API接口設計經(jīng)驗總結

　　1、在接口定義中確定MVC的GET或者POST方式

　　由于我們整個Web API平臺是基于MVC的基礎上進行的API開發(fā)，因此整個Web API的接口，在定義的時候，一般需要顯示來聲明接口是［HttpGet］或者［HttpPost］，雖然有些接口也可以不用聲明，但是避免出現(xiàn)類似下面的錯誤信息，顯式聲明還是有好處的。

　　請求的資源不支持 http 方法“POST

　　例如在基類定義的查找對象接口如下所示。

　　/// 《summary》

　　/// 查詢數(shù)據(jù)庫，檢查是否存在指定ID的對象

　　/// 《/summary》

　　/// 《param name=“id”》對象的ID值《/param》

　　/// 《returns》存在則返回指定的對象，否則返回Null《/returns》

　?。跦ttpGet］

　　public virtual T FindByID（string id， string token）

　　如果是增刪改的接口，一般需要聲明為POST方式提交數(shù)據(jù)，而且基于安全性的考慮，需要攜帶更多的參數(shù)。

　　/// 《summary》

　　/// 插入指定對象到數(shù)據(jù)庫中

　　/// 《/summary》

　　/// 《param name=“info”》指定的對象《/param》

　　/// 《returns》執(zhí)行操作是否成功?！?returns》

　?。跦ttpPost］

　　public virtual CommonResult Insert（T info， string token， string signature， string timestamp， string nonce， string appid）

　　2、動態(tài)對象的接口定義

　　在一般的Web API接口里面，我們可能都會碰到很多簡單類型的參數(shù)，但是又想讓它們以POST方式提交數(shù)據(jù)，那么我們就可以有兩種方法來處理，一種是定義一個類來放置這些參數(shù)，一種是采用動態(tài)的JObject參數(shù)，前者有很多不方便的地方，因為我們不可能為每個接口參數(shù)定義多一個實體類，這樣可能會有很多難以管理的類定義。如下面是微信API的調(diào)用接口案例，我們也需要設置這樣的處理規(guī)則。

　　接口調(diào)用請求說明

　　http請求方式： POST（請使用https協(xié)議）

　　https://api.weixin.qq.com/cgi-bin/groups/update？access_token=ACCESS_TOKEN

　　POST數(shù)據(jù)格式：json

　　POST數(shù)據(jù)例子：{“group”：{“id”：108，“name”：“test2_modify2”}}

　　那么我們采用JObject是這么樣的呢，我們來看接口的定義和處理代碼。JObject是Newtonsoft.Json.Linq命名空間下的一個對象。

　　/// 《summary》

　　/// 修改用戶密碼

　　/// 《/summary》

　　/// 《param name=“param”》包含userName和userPassword的復合對象《/param》

　　/// 《param name=“token”》用戶訪問令牌《/param》

　　/// 《returns》《/returns》

　　［HttpPost］

　　public CommonResult ModifyPassword（JObject param， string token）

　　{

　　//令牌檢查，不通過則拋出異常

　　CheckResult checkResult = CheckToken（token）;

　　dynamic obj = param;

　　if （obj ！= null）

　　{

　　string userName = obj.userName;

　　string userPassword = obj.userPassword;

　　bool success = BLLFactory《User》.Instance.ModifyPassword（userName， userPassword）;

　　return new CommonResult（success）;

　　}

　　else

　　{

　　throw new MyApiException（“傳遞參數(shù)出現(xiàn)錯誤”）;

　　}

　　}

　　其中我們把JObject對象轉換為我們所需要的對象的時候，因為我們沒有定義具體的實體類，因此采用了dynamic語法，聲明這是一個動態(tài)對象，由運行時獲取對應的屬性。

　　dynamic obj = param;

　　這樣我們就可以在調(diào)用的時候，動態(tài)POST對應的JSON對象給Web API接口，而不需要預先定義各種接口參數(shù)的類了。

　　/// 《summary》

　　/// 調(diào)用Web API接口，修改用戶密碼

　　/// 《/summary》

　　/// 《param name=“userName”》用戶名稱《/param》

　　/// 《param name=“userPassword”》修改的密碼《/param》

　　/// 《returns》如果修改成功返回true，否則返回false《/returns》

　　public bool ModifyPassword（string userName， string userPassword）

　　{

　　var action = “ModifyPassword”;

　　var postData = new

　　{

　　userName = userName，

　　userPassword = userPassword

　　}.ToJson（）;

　　string url = GetTokenUrl（action）;

　　CommonResult result = JsonHelper《CommonResult》.ConvertJson（url， postData）;

　　return （result ！= null） ？ result.Success ： false;

　　}

　　其中GetTokenUrl是根據(jù)token和API的地址等參數(shù)，構建一個完整的提交地址。我們在上面代碼通過

　　var postData = new

　　{

　　userName = userName，

　　userPassword = userPassword

　　}.ToJson（）;

　　就可以動態(tài)創(chuàng)建一個對象，并生成它的JSON字符串，把數(shù)據(jù)POST提交到對應的API接口里面即可，然后對結果進行對象的轉換就算完成了。