ASP.NET Web API 簡介

ASP.NET MVC 4 包含了 ASP.NET Web API， 這是一個創建可以連接包括瀏覽器、移動設備等多種客戶端的 Http 服務的新框架， ASP.NET Web API 也是構建 RESTful 服務的理想平臺。

ASP.NET Web API 特性

ASP.NET Web API 包含下列特性：

• 先進的 HTTP 編程模型： 使用新的強類型的 HTTP 對象模型直接操作 HTTP 請求和響應， 在 HTTP客戶端使用相同的編程模型和 HTTP 管道；

• 支持路由： Web API 完整支持 ASP.NET 路由， 包括路由參數和約束。 此外， 到動作的映射支持約定， 從此將不再需要向類或者方法添加類似于 [HttpPost] 之類的屬性；

• 內容協商： 客戶端與服務端可以一起決定 API 返回數據的格式。 默認支持 XML， JSON 以及 Form URL-Encoded 格式， 可以擴展添加自定義格式， 甚至可以替換掉默認的內容協商策略；

• 模型綁定與驗證： 模型綁定器可以輕易地從 HTTP 請求中提取數據并轉換成在動作方法中使用的 .Net 對象；
• 過濾： Web API 支持過濾， 包括總所周知的 [Authorize] 過濾標記， 可以為 Action 添加并插入自定義過濾， 實現認證、異常處理等；

• 查詢聚合： 只要簡單的返回 Iqueryable<T> ， Web API 將會支持通過 OData 地址約定進行查詢；

• 改進的 Http 細節可測試性： Web API 不是將 HTTP 細節設置到一個靜態的 Context 對象上， 而是使用 HttpRequestMessage 和 HttpResponseMessage 實例， 可以使用這些對象的泛型版本為這些 Http 類型添加自定義類型；
• 改進的依賴反轉 (IoC) 支持： Web API 使用 MVC Dependency Resolver 實現的服務定位器模式在不同的場景下來獲取實例；

• 基于代碼的配置： Web API 單獨使用代碼完成配置， 從而保證了配置文件的整潔；

• 自托管 (Self-Host) ： Web API 除了可以托管在 IIS 中， 還可以托管在進程中，依舊可以使用路由以及其它的特性。

第一個 Web API 程序

從零開始創建 Web API 項目

1、 創建一個空的 ASP.NET 4.0 網站項目

2、 添加對 System.Net.Http , System.Net.Http.Formatting , System.Web.Http , System.Web.Http.Common , System.Web.Http.WebHost 的引用

3、 添加 Global Application Class ， 并在 Global 類中的 Application_Start 方法中添加如下代碼：

RouteTable.Routes.MapHttpRoute(
   name: "DefaultApi",
   routeTemplate: "api/{controller}/{id}",
   defaults: new {
      id = RouteParameter.Optional
   }
);

4、添加一個 ProductsController ， 繼承自 ApiController ， 代碼如下：

public  class ProductController : ApiController {

   public IQueryable GetAllProducts() { ... }

   public Product GetProductById(int id) { ... }

}

5、 在瀏覽器輸入 URI 訪問資源， 也可以通過腳本等任何客戶端進行訪問， 以瀏覽器為例：

在地址欄輸入 http://localhost:64334/api/products 將會訪問到 GetAllProducts 方法， 返回所有的 Product 實例；

在地址欄輸入 http://localhost:64334/api/products /1 將會訪問到 GetProductById 方法， 返回指定 id 的 Product 實例；

理解 API 路由

對于每一個 Http 消息， ASP.NET Web API 框架通過路由表決定由哪個控制器處理請求。 當你創建一個新的 Web API 項目時， 將會包含一個類似這樣的一個默認的路由：

/api/{controller}/{id}

{controller} 和 {id} 是兩個占位符， 當遇到一個符合這種樣式的 URI ， 將將會開始尋找合適的控制器方法進行調用， 規則如下：

• {controller} 用來與控制器名稱像匹配；
• HTTP 請求的方法用來與方法名稱匹配； （本規則只適用于 GET, POST, PUT 和 DELETE）
• {id} ， 如果有， 將會用于和方法的 id 參數進行匹配；

這里有一些請求的例子， 以及基于當前實現情況的的 HTTP 動作結果：

在第一個例子中， 與 "products" 相匹配的是 ProductsController ， HTTP 請求的方法是 GET ， 所以框架開始在 ProductController 類里面尋找以 “Get” 開頭的方法， 此外， URI 中沒有提供 id 參數， 所以框架要找一個沒有參數的方法， 最后， ProductsController 的 GetAllProducts 方法滿足要求。

第二個例子與第一個類似， 不同的是 URI 里面包含了 {id} 參數。 因此， 框架調用 GetProduct 方法， 因為它需要一個名稱為 id 參數。 值得注意的是， URI 里面的 id 參數是字符串類型的 “5” ， 框架會根據方法的簽名自動把它轉換成整形。

在第三個例子中， 客戶端發起 HTTP Post 請求， 框架尋找名稱以 “Post” 開始的方法。 而 ProductController 類沒有這樣的方法， 所以框架返回的 HTTP 狀態碼是 405 ， 表示不允許調用的方法 （Method Not Allowed） 。

再看第四個例子， 客戶端發送一個 GET 請求到 /api/users 。 框架尋找名稱為 UserController 的控制器， 這樣的類還沒有定義， 所以框架返回的 HTTP 狀態碼是 404 ， 表示請求的資源未找到。

Web API CURD

什么是 CURD

CURD 是指 Create 、 Update 、 Read 、 Delete 四個簡單的數據庫操作， 通常大多數 Web 服務也通過 REST 風格的服務提供這些操作。

接下來將繼續完善 ProductsController 以支持下面所有的操作：

資源

ProductController 提供了兩種 URI 資源：

HTTP 的四個主要方法 （GET， PUT， POST， DELETE） 按照下列方式映射為 CURD 操作：

• GET 用于獲取 URI 資源的進行展示， GET 操作不應對服務端有任何影響；
• PUT 用于更新 URI 上的一個資源， 如果服務端允許， PUT 也可以用于新建一個資源；
• POST 用于新建 資源， 服務端在指定的 URI 上創建一個新的對象， 將新資源的地址作為響應消息的一部分返回；
• DELETE 用于刪除指定的 URI 資源。

實現 CURD

新建資源

客戶端發起 HTTP POST 請求新建資源， 為了能處理 POST 請求， 需要在 ProductController 定義一個以 Post 開頭的方法， 這個方法接受一個類型為 Product 的參數。

根據 HTTP/1.1 協議， 需要注意的問題有：

• 響應代碼： Web API 默認返回的響應代碼是 200 (OK) ， 但是根據 HTTP/1.1 協議， POST 請求并創建資源的響應代碼應該是 201 (Created)；
• 地址： 當服務器創建資源之后， 應該在響應的 Header 里面包含新資源的地址。

新建資源的最終代碼如下：

public HttpResponseMessage PostProduct(Product product) {
   this._dbContext.Save(product);
   var result = new HttpResponseMessage(product, HttpStatusCode.Created);
   var location = Url.Route(null, new { id = product.ProductID });
   result.Headers.Location = new Uri(location);
   return result;
}

更新資源內容

更新是比較簡單的， 代碼如下：

public HttpResponseMessage PutProduct(int id, Product product) {
   if (!this._dbContext.Products.Any(p => p.ProductID == id)) {
      throw new HttpResponseException(HttpStatusCode.NotFound);
   }
   product.ProductID = id;
   this._dbContext.Update(product);
   return new HttpResponseMessage(HttpStatusCode.OK);
}

該方法需要兩個參數， id 從 URI 中獲取， product 從客戶端請求消息中獲取。

刪除資源

根據 HTTP 協議， 刪除應當是冪等的， 也就是說一個 URI 上接受到多少個刪除請求都是相同的， 如果資源已經被刪除， 也不能返回錯誤的響應代碼。

如果成功刪除了資源， 可以返回 200 (OK) 響應代碼， 以及一個實體進行狀態說明， 或者返回 204 (No Content)。

如果刪除需要等待事務完成， 則應該返回 202 (Accepted) 。

刪除資源的實現代碼如下：

public HttpResponseMessage DeleteProduct(int id) {
   var product = this._dbContext.Products.FirstOrDefault(p => p.ProductID == id);
   this._dbContext.Delete(product);
   return new HttpResponseMessage(HttpStatusCode.NoContent);
}