ASP.NET Web API 简介

Posted 2020-07-09 StarkSoft

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); }