教你如何构建简单的Web API

WCF Web API支持多个宿主环境：自宿主（windows服务或者控制台）和IIS宿主（asp.net webform/mvc）。这个入门文章主要演示在ASP.NET MVC3网站宿主：

• 如何使用NuGet向项目中添加Web Api引用
• 如何创建一个通过HTTP GET访问的Web Api
• 如何通过asp.net routes宿主一个Web Api
• 如何通过浏览器或者Fiddler访问Web Api
• 如何在Api上启用OData uri查询

　　1、创建一个基本的解决方案：使用VS2010新建一个空的ASP.NET MVC 3 Web Application

　　设置站点的端口号为9000

　　2、向解决方案中加入Web Api的引用

　　通过NuGet来添加Web api的程序集引用，右击项目属性，选择Manage NuGet Packages

　　在NuGet管理扩展器上查询Online的webapi.all

　　选择安装，NuGet就会下载所有所需的软件包，现在可以开始开发Web Api。

　　3、创建一个Contacts Api类

　　右击项目ContactManager选择添加一个文件夹，取名APIs，然后在APIs文件夹上右击添加类，类名叫做ContactsApi：

using System.ServiceModel;
namespace ContactManager.APIs
{
[ServiceContract]
publicclass ContactsApi
{
}
}

　　ContractsApi 加了ServiceContractAttribute表示这是一个WCF 服务，将通过HTTP方式暴露出来。

　　 4、通过asp.net routing注册ContractsApi Api需要通过asp.net mvc宿主，使用ASP.net Route的MapServiceRoute扩展方法把它注册进去。切换到global.asax.cs文件，添加以下引用

using ContactManager.APIs;
using Microsoft.ApplicationServer.Http.Activation;

　　在RegisterRoutes方法里加入下述代码

routes.MapServiceRoute<ContactsApi>("api/contacts");

　　下面的黄色部分很重要，MVC的默认路由是映射到controller + action

publicstaticvoid RegisterRoutes(RouteCollection routes)
{
routes.IgnoreRoute("{resource}.axd/{*pathInfo}");


routes.MapServiceRoute<ContactsApi>("api/contacts");

routes.MapRoute(
"Default", // Route name
"{controller}/{action}/{id}", // URL with parameters
new { controller ="Home", action ="Index", id = UrlParameter.Optional } // Parameter defaults
);
}

　　MapServiceRoute需要一个泛型参数指定服务（API），以及一个将被追加到IIS base url的路径。在这里，我们指定的contacts，也就是宿主为http://localhost:9000/api/contacts。

　　5. 通过一个HTTP Get 方法暴露contacts：首先创建一个poco（Plain Old C#）Contract类，代表我们在api上传递的联系人，本质上就是一个DTO（数据传输对象），在HTTP上我们把它作为资源，然后创建一个HTTP Get方法暴露资源。

　　右击项目ContactManager项目选择添加新的文件夹Resources，在Resources文件下创建一个新的类Contact。

namespace ContactManager.Resources
{
publicclass Contact
{
publicint ContactId { get; set; }
publicstring Name { get; set; }
}
}

　　返回到ContactApi类，添加下述引用：

using System.ServiceModel.Web;
using ContactManager.Resources;

　　添加一个Get方法返回所有的contracts

[WebGet(UriTemplate ="")]
public IQueryable<Contact> Get()
{
var contacts =new List<Contact>()
{
new Contact {ContactId =1, Name ="Phil Haack"},
new Contact {ContactId =2, Name ="HongMei Ge"},
new Contact {ContactId =3, Name ="Glenn Block"},
new Contact {ContactId =4, Name ="Howard Dierking"},
new Contact {ContactId =5, Name ="Jeff Handley"},
new Contact {ContactId =6, Name ="Yavor Georgiev"}
};
return contacts.AsQueryable();
}

　　Get方法上加了WebGet Attribute表示这是一个HTTP Get。注意这里的UriTemplate被设置为，默认情况下，操作的Uri是方法名Get，在这种情况下，我们是在Route中设置的Uri。

　　6、通过浏览器查询Contracts.按F5运行项目，然后再浏览器地址栏中输入http://localhost:9000/api/contacts

　　7、查询返回Json格式的Contracts。HTTP提供了一些内容协商机制 — 当有多个可得的表现形式的时候，对特定的响应选择最好的表现形式的处理过程。

　　服务器驱动协商（Server-driven Negotiation）

　　如果响应的最好的表现形式的选择是通过服务器上的算法来实现，那么这种方式的协商称做服务器驱动协商。选择是基于响应可得的表现形式（根据不同的维度，响应会不同；例如，语言，内容编码，等等）和请求消息里特定的头域或关于请求的其他信息（如：网络客户端的地址）。 
　　服务器驱动协商是有优点的，当从可行的表现形式里进行选择的算法对用户代理进行描述是比较困难的时候，或者当服务器期望发送最好的猜测给客户端而只通过一个响应（以避免后续请求的回路（一个请求会返回一个响应）延迟如果此最好的猜测对用户适合的时候）的时候。为了改善服务器的猜测，用户代理应该包含请求头域（Accept，Accept-Language，Accept-Encoding，等等），这些头域能描述它对响应的喜好。

　　Web api返回的响应很容易添加一种媒体类型（media types )。

　　打开Fiddler，在Request builder栏输入地址http://localhost:9000/api/contacts，然后移动到Request Headers在User-Agent 项下方添加 Accept: application/json

　　按下 Exectue按钮，双击左边的Panel查看HTTP的response，切换到RawTab，你可以看到下面的json格式的数据：

　　8、启用OData 查询支持

　　Web API支持OData协议，接受OData的URI格式查询，当OData 查询到达Web Api， 在返回客户端之前在服务端会进行必要的过滤和排序。查询使用IQueryable 接口，服务端并没有去查询所有的数据，发送过滤和排序到服务端。

return contacts.AsQueryable();

　　运行程序，在浏览器里输入 http://localhost:9000/api/contacts?$Top=4&$OrderBy=Name ，看到浏览器之返回了按名字排序的top 4个contract

　　也可以通过Fidder去查询，具体可参照第7步。

　　总结

　　通过这个Quick start，我们学习到了以下内容

• 如何使用NuGet向项目中添加Web Api引用
• 如何创建一个通过HTTP GET访问的Web Api
• 如何通过asp.net routes宿主一个Web Api
• 如何通过浏览器或者Fiddler访问Web Api
• 如何在Api上启用OData uri查询