API-6_1 初識Web API
初識 Web API
一、 Web API簡介
XML：可擴充套件標記語言，可以用來標記資料、定義資料型別，是一種允許使用者對自己的標記語言進行定義的源語言。格式統一、跨平臺和程式語言，業界公認的標準，非常適合 Web 傳輸。XML檔案龐大，檔案格式複雜，傳輸佔頻寬；伺服器端和客戶端都需要花費大量程式碼來解析XML，導致伺服器端和客戶端程式碼變得異常複雜且不易維護；客戶端不同瀏覽器之間解析XML的方式不一致，需要重複編寫很多程式碼，花費較多的資源和時間。
JSON：一種輕量級的資料交換格式，具有良好的可讀和便於快速編寫的特性，在不同平臺之間進行資料交換，為理想的資料交換語言。資料格式比較簡單，具有陣列和字典的特徵，易於讀寫，格式都是壓縮的，佔用頻寬小，傳輸速度快；易於解析，客戶端JavaScript可以簡單的通過eval()進行JSON資料的讀取；支援多種語言，便於伺服器端的解析。
- 1. WebAPI概念
API（Application Programming Interface,應用程式程式設計介面）
Web API ：基於網際網路的應用程式程式設計介面（使用HTTP協議，80埠進行訪問和互動），網際網路的服務提供者。
ASP.NET Web API 支援讓你能夠輕鬆地建立功能強大的 Web API 程式介面，可以從範圍廣泛的客戶端 （包括使用 JavaScript 的瀏覽器，移動客戶端，本機應用程式等）訪問。構建一個基於 HTTP 協議的 Client/ Server 模式的服務架構。Web API最重要的是可以構建面向各種客戶端的服務。
在MVC中增加了Web API，Web API和WebService一樣都可以讓你建立一個HTTP服務，可以簡單理解為基於REST風格的WebService，但是還是有很多不同點。如WebService基於XML，Web API基於JSON。
Web API在ASP.NET完整框架中地位
在圖上可以看出來，Web API 與SignalR一起同為構建Service的框架。Web API負責構建http常規服務，而SingalR主要負責的是構建實時服務，例如股票，聊天室，線上遊戲等實時性要求比較高的服務
SignaIR是ASP.NET下的一個庫，可用於web專案中的實時通訊，可以讓伺服器端程式碼向客戶端推送內容，而不是等待客戶端請求資料。
- 2. Web API和Web Service的區別
Web API
l 這是一個簡單的構建HTTP服務的新框架。
l 在.NET平臺上Web API是一個開源的、理想的、構建REST-ful服務的技術。
l 他也支援MVC的特徵，像路由、控制器、Action、Filter、模型繫結、控制反轉（IOC）或依賴注入（DI），單元測試。這些可以使程式更簡單、更健壯。
l 他可以部署在應用程式和IIS上。
l 這是一個輕量級的框架，並且對限制頻寬的裝置，比如智慧手機等支援的很好。
l 返回值可以被Web API的MediaTypeFormatter轉換成JSON、XML 或者任何你想轉換的格式
Web Service
l 它是基於SOAP協議的，資料格式是XML。
l 只支援HTTP協議，只能部署在IIS上。
l 它不是開源的，但可以被任意一個瞭解XML的人使用。
- 3. Web API 與MVC的區別
l MVC主要用來構建網站，既關心資料也關心頁面展示，而Web API只關注資料
l Web API支援格式協商，客戶端可以通過Accept header通知伺服器期望的格式
l Web API支援Self Host，MVC目前不支援
l Web API通過不同的http verb表達不同的動作(CRUD)，MVC則通過Action名字表達動作
l Web API內建於ASP.NET System.Web.Http名稱空間下，MVC位於System.Web.Mvc名稱空間下，因此model binding/filter/routing等功能有所不同
l 最後，Web API非常適合構建移動客戶端服務
- 4. 什麼地方需要用Web API
當你遇到以下這些情況的時候，就可以考慮使用Web API了。
l 需要Web Service但是不需要SOAP
l 需要在已有的WCF服務基礎上建立non-soap-based http服務
l 只想釋出一些簡單的Http服務，不想使用相對複雜的WCF配置
l 釋出的服務可能會被頻寬受限的裝置訪問
l 希望使用開源框架，關鍵時候可以自己除錯或者自定義一下框架
二、 建立Web API
- 1. 使用Web API模板建立Web API，專案結構如下圖
l 新生成的WebAPI專案和典型的MVC專案一樣，包含主要的Models、Views、Controllers等資料夾和Global.asax檔案。Area在專案中可以稱之為區域，每個Area代表應用程式的不同功能模組，Area 使每個功能模組都有各自的資料夾，資料夾中有自己的Controller、View和Model。
l Views對於WebAPI來說沒有太大的用途。
l Models中的Model主要用於儲存Service和Client互動的物件，這些物件預設情況下會被轉換為JSON格式的資料進行傳輸。
l Controllers中的Controller對應於WebService來說是一個Resource，用於提供服務。和普通的MVC一樣。
l Global.asax用於配置路由規則
專案會自動新增一個 Web API 控制器，在 Controllers 目錄中的 ValuesController.cs 檔案，提供了Web API 標準訪問介面示例，並附帶訪問地址。
執行專案。專案模板自動生成的API開發文件
API介面文件，這裡顯示了控制器名稱，介面地址，以及介面描述資訊
- 2. Web API的主要功能
l 請求的回覆通過Http Status Code表達不同含義（404，403，200，500等），並且客戶端可以通過Accept Header來與伺服器協商格式，例如你希望伺服器返回JSON格式還是XML格式。
200 請求已成功
400 語義有誤，當前請求無法被伺服器理解；請求引數有誤
403 伺服器已經理解請求，但是拒絕執行它
404 請求失敗，請求所希望得到的資源未被在伺服器上發現
500 伺服器遇到了一個未曾預料的狀況，導致了它無法完成對請求的處理
l MVC WebAPI中的Controllers和普通MVC的Controllers類似，但不再繼承於Controller，而改為繼承API的ApiController。
l MVC WebAPI 基於 Http 動作 (GET, POST, PUT, DELETE) 實現 CRUD (create, retrieve, update, delete) 操作，通過不同的 HTTP 動作表達不同的含義，這樣就不需要暴露多個 API 來支援這些基本操作。
l 一個Controller預設包含5個Action。分別對應對於資料表的5個操作
URL路由匹配表
|
URL |
HttpMethod |
對應的Action名 |
|
api/User |
GET |
Get() |
|
api/User/1 |
GET |
Get(int id) |
|
api/User |
POST |
Post([FromBody]string value) |
|
api/User/1 |
DELETE |
Delete(int id) |
|
api/User/22 |
PUT |
Put(int id, [FromBody]string value) |
路由規則預設情況下，模板自帶了兩個路由規則，分別對應於Web API和普通MVC的Web請求，預設的Web API路由規則如下。
routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
);
可以看到，預設路由使用的固定的API作為URI的先導，按照微軟官方的說法，用於區分普通Web呼叫和Web Service的呼叫路徑：
Web API和MVC裡面的路由有點不同，Web API的預設路由是通過HTTP的方法（GET / POST / PUT / DELETE）去匹配對應的Action，也就是說Web API 的預設路由並不需要指定Action的名稱。
三、 API文件
Web API模板建立專案，模板中會自動提供一個HelpPage介面文件，方便我們很方便的檢視文件資訊。但是預設的介面文件使用過程中還是有很多不方便的地方，例如很多的英文描述，以及沒有解釋介面作用，引數沒有介紹等，都會給閱讀者帶來各種障礙，導致需要額外的人工溝通去解釋如何使用
- 1. 設定介面描述資訊
在平時編寫程式程式碼時，我們可以在方法定義程式碼上一行輸入“///”符號，來給這段程式碼寫註釋，方便以後閱讀。
HelpPage文件工具是可以自動將“///”的註釋資訊提取到介面文件中用來解釋介面用途，引數描述資訊的。
- 2. 配置HelpPage文件，顯示輸出XML檔案，啟用自定義介面描述資訊顯示
1) 在解決方案資源管理器中，選擇當前專案點選滑鼠右鍵 -> 屬性 -> 選擇生成，在頁面下部找到輸出， 在其中進行如下設定，勾選 XML 文件檔案，並設定名稱，名稱可以自定義，但是注意要與以後使用時名稱一致
2) 開啟 \Areas\HelpPage\App_Start\HelpPageConfig.cs 檔案，取消如下程式碼註釋，並修改路徑與 上條 XML 文件檔案設定一致。
config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/bin/Qin_WebAPI_HelloWorld.xml")));
3) 在 Web API 控制器中編寫方法描述資訊
4) 執行測試
- 3. 修改介面文件檢視檔案，優化介面顯示
在 /Areas/HelpPage 目錄中包含有 Web API 介面文件頁面的 MVC 專案 , 在 Views 子目錄中，包含了網 站裡面的所有檢視模板。我們可以在這裡找到我們需要修改的內容。
l Views/Help/Index.cshtml：這是 Web API介面文件的首頁模板，這裡可修改文件標題、介紹資訊等。
l Views/Help/DisplayTemplates/ApiGroup.cshtml：這是介面組的顯示模板，這裡可修改顯示介面的表格的標題等。
l Views/Help/DisplayTemplates/HelpPageApiModel.cshtml：這是某介面具體用法的顯示模板，這裡可修改請求引數、返回值資源的描述等。
四、 Web API控制器中的Action方法有如下幾種返回型別：
|
返回型別 |
Web API建立HTTP響應訊息的機制 |
|
void |
返回HTTP狀態碼204(無內容) |
|
HttpResponseMessage |
直接轉換成HTTP響應訊息 |
|
IHttpActionResult |
呼叫介面的ExecuteAsync方法建立一個HttpResponseMessage物件，然後轉換成HTTP響應訊息 |
|
其它型別 |
把序列化後的返回值寫入響應正文，並且返回HTTP狀態碼200(OK) |
- 1. Void
void宣告的介面，在請求成功的時候得不到返回值，而且會返回http的狀態碼為204，表示沒有返回值
- 2. HttpResponseMessage
HttpResponseMessage這個物件，表示向客戶端返回一個http響應的訊息物件（包含http狀態碼和需要返回客戶端的訊息）。這個物件也有它獨特的使用場景：需要向客戶端返回HttpResponse時就要用到這個物件。
- 3. IHttpActionResult
IHttpActionResult是WebApi最常用的一種返回值型別，常用的方式有：Json(T content)、Ok()、 Ok(T content)、NotFound()、Content(HttpStatusCode statusCode, T value)、BadRequest()、Redirect(string location)、StatusCode(HttpStatusCode statusCode)等
l 返回 Json(T content)，返回的是JsonResult物件，如return Json<List<userinfo>>(list);；也可以使用dynamic來返回一個物件，如：return Json<dynamic>(new { AA = "a", BB = "b" });
l 如果返回Ok()，就表示不向客戶端返回任何資訊，只告訴客戶端請求成功，如return Ok();；Ok(T content)向客戶端返回一個成功的物件，如：return Ok(result);。
l NotFound()方法會返回一個404的錯誤到客戶端，如：return NotFound()；
l Content(HttpStatusCode statusCode, T value)，向客戶端返回值和http狀態碼，如：return Content<string>(HttpStatusCode.OK, "OK");。
l BadRequest() 向客戶端返回400的http錯誤，如：return BadRequest();
l Redirect(string location) 將請求重定向到其他地方，如：
return Redirect("http://localhost:7408/api/Values/getJson1");
l StatusCode(HttpStatusCode statusCode)：方法中傳入一個HttpStatusCode列舉型別，這裡面提供HTTP協議所有的狀態碼。
- 4. 其它型別
你也可以將webapi的介面和普通方法一樣，返回任意的型別，WebApi會自動序列化你自定義任何返回型別，然後將序列化的值寫到響應正文裡，狀態碼統一返回200。
基於上面幾種不同的返回型別，Web API建立HTTP響應訊息的機制也不同。