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 方法中添加如下代码：




1

2

3

4

5

6

7




RouteTable.Routes.MapHttpRoute(

   name:
"DefaultApi",

   routeTemplate:
"api/{controller}/{id}",

   defaults:
new {

      id
 = RouteParameter.Optional

   }

);




4、添加一个 ProductsController ， 继承自 ApiController ， 代码如下：




1

2

3

4

5

6

7




public  class ProductController
 : ApiController {

 

   public IQueryable<product>
 GetAllProducts() { ... }

 

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

 

}</product>




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 动作结果：

HTTP Method

URI

Action

GET

/api/products

GetAllProducts

GET

/api/products/5

GetProduct(5)

POST

/api/products

HTTP Status 405

GET

/api/users/

HTTP Status 404
在第一个例子中， 与 "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 以支持下面所有的操作：



动作


HTTP 方法



相对路径



获取全部



GET



/api/products


指定 id 获取



GET



/api/products/id



添加



POST



/api/products



更新



PUT



/api/products/id



删除



DELETE



/api/products/id



资源
ProductController 提供了两种 URI 资源：



资源



地址



全部产品列表



/api/products



单个产品



/api/products/id



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 里面包含新资源的地址。
新建资源的最终代码如下：




1

2

3

4

5

6

7




public HttpResponseMessage<product>
 PostProduct(Product product) {

   this._dbContext.Save(product);

   var result
 = new HttpResponseMessage<product>(product,
 HttpStatusCode.Created);

   var location
 = Url.Route(null,
new {
 id = product.ProductID });

   result.Headers.Location
 = new Uri(location);

   return result;

}</product></product>




更新资源内容
更新是比较简单的， 代码如下：




1

2

3

4

5

6

7

8




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) 。
删除资源的实现代码如下：




1

2

3

4

5




public HttpResponseMessage
 DeleteProduct(int id)
 {

   var product
 = this._dbContext.Products.FirstOrDefault(p
 => p.ProductID == id);

   this._dbContext.Delete(product);

   return new HttpResponseMessage(HttpStatusCode.NoContent);

}