初尝Web API《转》

HTTP 并不是只能用在网页中。它其实还是一个强大的平台，可以用来生成一些API，暴露服务和数据。HTTP很简单灵活，还非常普及。几乎所有你能想到的平台都有HTTP库，所以HTTP服务可以囊括很大范围的客户端，包括浏览器，移动设备和传统的桌面程序。

ASP.NET Web API 是.NET Framework上的一个框架，用来生成 web API。本文将使用ASP.NET Web API来创建一个web API，返回一组商品。前端页面用jQuery来显示结果。

点此下载完整工程。

首先需要安装了ASP.NET MVC 4的 Visual Studio 。下面的用哪个都行：

Visual Studio 2012
Visual Studio Express 2012 for Web
Visual Studio 2010 且已安装 ASP.NET MVC 4 。
Visual Web Developer 2010 Express 且已安装 ASP.NET MVC 4 。

如果用的是 Visual Studio 2010 或者 Visual Web Developer 2010 Express ，需要另外安装 ASP.NET MVC 4 。本文的截图都是用的 Visual Studio Express 2012 for Web。

创建 Web API 工程

启动 Visual Studio ，在开始页里选择“新建项目”。或者从“文件”菜单里，选择“新建项目”。

在模板面板中，选择“已安装”，并展开 Visual C# 节点。在 Visual C# 下面，选择 Web。在项目模板列表中，选择 ASP.NET MVC 4 Web 应用程序。将项目命名为 "HelloWebAPI" 然后点击“确定”。

在弹出的“新 ASP.NET MVC 4 项目”对话框中，选择“Web API”然后点“确定”。

添加模型

模型是指程序里的对象。 ASP.NET Web API 能够自动序列化模型为JSON，XML或者其它的格式，然后将序列化后的数据写入HTTP响应信息体里。只要客户端能读到序列化格式，它就能反序列化为对象。大部分的客户端都能够解析XML或JSON。而且，客户端通过设置HTTP请求信息里的Accept头就能够表明它想要什么样的格式。

我们就创建一个表示商品的模型来开始吧。

如果解决方案资源管理器没显示的话，点击“视图”菜单并选择“解决方案资源管理器”。在解决方案资源管理器重，右击“Models”文件夹。在弹出菜单中，选择“添加“，”类“。

将类命名为 "Product"。接下来在 Product 类里加入下面的属性：

namespace HelloWebAPI.Models

{

    public class Product

    {

        public int Id { get; set; }

        public string Name { get; set; }

        public string Category { get; set; }

        public decimal Price { get; set; }

    }

}

添加控制器

控制器是一个处理HTTP请求的对象。当你创建完项目以后，”新建项目“向导就自动创建了2个控制器。在解决方案资源管理器里展开”Controllers“目录就能看到了。

HomeController 是一个传统的 ASP.NET MVC 控制器。它只是负责处理站点的HTML页，跟Web API没有直接关系。
ValuesController 是一个示例 WebAPI 控制器。

注意如果你之前已经搞过 ASP.NET MVC，那你肯定已经对控制器很熟了。它在Web API里也是类似的，只不过在Web API里控制器不是从Controller类继承而是从ApiController类继承了。你会注意到，第一个主要的不同点是Web API上的操作并不返回视图，而是返回数据。

解决方案资源管理里右击 ValuesController, 选择”删除“直接把他删掉。

如下所示，添加一个新的控制器：

解决方案资源管理里，右击 Controllers 目录，选择”添加“，”控制器“：

在”添加控制器“向导中，将控制器命名为 "ProductsController"。”模板“下拉框中，选择”空API控制器“。然后点”添加“。

”添加控制器“向导在Controllers目录下创建一个名为 ProductsController.cs 的控制器。

没有必要非得把控制器放到Controllers目录里。目录名并不重要，只是为了方便我们组织代码文件，这么起名比较简单。

如果这个文件没有打开，那就双击它打开（译注：老外真是啰嗦，像唐僧似的……）。添加如下的实现代码：

namespace HelloWebAPI.Controllers

{

    using HelloWebAPI.Models;

    using System;

    using System.Collections.Generic;

    using System.Linq;

    using System.Net;

    using System.Net.Http;

    using System.Web.Http;

    public class ProductsController : ApiController

    {

        Product[] products = new Product[]

        {

            new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 },

            new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M },

            new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M }

        };

        public IEnumerable<Product> GetAllProducts()

        {

            return products;

        }

        public Product GetProductById(int id)

        {

            var product = products.FirstOrDefault((p) => p.Id == id);

            if (product == null)

            {

                throw new HttpResponseException(HttpStatusCode.NotFound);

            }

            return product;

        }

        public IEnumerable<Product> GetProductsByCategory(string category)

        {

            return products.Where(

                (p) => string.Equals(p.Category, category,

                    StringComparison.OrdinalIgnoreCase));

        }

    }

}

为了让例子保持简单，我们直接把产品存到控制器类里的一个固定数组里。当然，在实际的程序里需要从数据库里查询或者用其它的一些外部数据源。

控制器定义了三个方法，要么返回单个商品，要么返回一组产品：

GetAllProducts 方法返回所有的产品，返回类型为 IEnumerable<Product> 。
GetProductById 方法通过ID查询某个产品。
GetProductsByCategory 方法返回指定分类的所有产品。

完事儿了！web API已经能用了。每一个控制器上的方法都对应了一个URI：

控制器方法	URI
GetAllProducts	/api/products
GetProductById	/api/products/id
GetProductsByCategory	/api/products/?category=category

客户端只要通过放松一个HTTP GET请求到URI就可以调用相应的方法。待会儿我们来看看这个映射是怎么做的。但首先我们先把它跑起来试试。

从浏览器调用 Web API

任何HTTP客户端都可以用来调用 web API。其实可以从web浏览器直接调用。

在 Visual Studio 里，选择“调试”菜单，然后“启动调试”，或者按F5键。 ASP.NET Development Server 就会启动起来（译者注：在VS2012默认的应该是IIS Express），在屏幕的右下角会出现一个通知图标，显示它正运行在哪个端口。默认情况下， Development Server 会选择一个随机的端口号。

然后Visual Studio 会自动打开浏览器窗口， URL 指向 http//localhost:xxxx/， xxxx 就是端口号。首页应该看起来如下图：

首页是一个 ASP.NET MVC 视图，由 HomeController 类返回。想要调用 web API，就得用到前边儿列出来的URI之一。比如，要获取所有商品列表，那就浏览 http://localhost:xxxx/api/products/. (将 "xxxx" 替换为真实的端口号)

实际显示结果要看你使用什么浏览器来决定。IE会提示你打开或保存一个名为products的“文件”。

这个“文件”其实只是HTTP响应体。点击“打开”。在“打开方式”对话框“，选择”记事本“。点击”确定“，弹出提示的时候点”打开“。文件应该包含了一个JSON，表示产品的数组。

[{"Id":1,"Name":"Tomato soup","Category":"Groceries","Price":1.0},{"Id":2,"Name":

"Yo-yo","Category":"Toys","Price":3.75},{"Id":3,"Name":"Hammer","Category":

"Hardware","Price":16.99}]

如果是Mozilla Firefox，会在浏览器里以XML形式显示列表。

为什么会不一样呢？因为 Internet Explorer 和 Firefox 发送了不同的 Accept 头，所以 web API 在响应里就发送了不同的内容类型。

自己浏览这俩 URI 试试：

http://localhost:xxxx/api/products/1
http://localhost:xxxx/api/products?category=hardware

第一个应该返回ID等于1的条目。第二个应该返回Category等于”hardware“的所有产品列表（这里只有一个条目）。

用JavaScript和jQuery调用 Web API

前一节里我们直接在浏览器里访问 web API 。但是大部分 web API 主要目的还是有客户端程序以编程方式来用。所以我们来写一个简单的JavaScript客户端。

在解决方案资源管理器重，展开Views目录，然后展开它下面的Home目录。可以看到一个名为Index.cshtml的文件。双击这个文件打开。

Index.cshtml 使用 Razor 视图引擎渲染HTML页。但是此处我们不使用任何Razor特性，因为我要演示客户端如何使用纯HTML和Javascript访问服务。因此，删掉这个文件里的所有东西，用下面的代码替换之：

<!DOCTYPE html>

<html lang="en">

<head>

    <title>ASP.NET Web API</title>

    <link href="../../Content/Site.css" rel="stylesheet" />

    <script src="../../Scripts/jquery-1.7.1.min.js" type="text/javascript">

        // TODO Add script

    </script>

</head>

<body id="body" >

    <div class="main-content">

        <div>

            <h1>All Products</h1>

            <ul id="products"/>

        </div>

        <div>

            <label for="prodId">ID:</label>

            <input type="text" id="prodId" size="5"/>

            <input type="button" value="Search" onclick="find();" />

            <p id="product" />

        </div>

    </div>

</body>

</html>

获取产品列表

要获取产品列表，通过发送 HTTP GET 请求到 "/api/products"。可以像下面这样用jQuery来实现：

<script type="text/javascript">

    $(document).ready(function () {

        // Send an AJAX request

        $.getJSON("api/products/",

        function (data) {

            // On success, 'data' contains a list of products.

            $.each(data, function (key, val) {

                // Format the text to display.

                var str = val.Name + ': $' + val.Price;

                // Add a list item for the product.

                $('<li/>', { text: str })    

                .appendTo($('#products'));  

            });

        });

    });

</script>

getJSON 函数用来发送 AJAX 请求。响应将是一个JSON对象数组。getJSON的第二个参数是一个回调函数，当请求成功完成时将调用。

通过ID获取产品

要根据ID获取产品，通过发送 HTTP GET 请求到 "/api/products/id"，这里的id就是产品的ID。将以下代码添加到脚本块儿里：

function find() {

    var id = $('#prodId').val();

    $.getJSON("api/products/" + id,

        function (data) {

            var str = data.Name + ': $' + data.Price;

            $('#product').text(str);

        })

    .fail(

        function (jqXHR, textStatus, err) {

            $('#product').text('Error: ' + err);

        });

}

我们再一次通过调用 jQuery 的 getJSON 函数来发送 AJAX 请求，但这次我们用ID来构造这个请求URI。这个请求的响应是一个JSON，表示单个产品对象。

完整的 Index.cshtml 文件如下：

<!DOCTYPE html>

<html lang="en">

<head>

    <title>ASP.NET Web API</title>

    <link href="../../Content/Site.css" rel="stylesheet" />

    <script src="../../Scripts/jquery-1.7.1.min.js"

        type="text/javascript"></script>

        <script type="text/javascript">

            $(document).ready(function () {

                // Send an AJAX request

                $.getJSON("api/products/",

                function (data) {

                    // On success, 'data' contains a list of products.

                    $.each(data, function (key, val) {

                        // Format the text to display.

                        var str = val.Name + ': $' + val.Price;

                        // Add a list item for the product.

                        $('<li/>', { text: str })

                        .appendTo($('#products'));

                    });

                });

            });

            function find() {

                var id = $('#prodId').val();

                $.getJSON("api/products/" + id,

                    function (data) {

                        var str = data.Name + ': $' + data.Price;

                        $('#product').text(str);

                    })

                .fail(

                    function (jqXHR, textStatus, err) {

                        $('#product').text('Error: ' + err);

                    });

            }

        </script>

</head>

<body id="body" >

    <div class="main-content">

        <div>

            <h1>All Products</h1>

            <ul id="products"/>

        </div>

        <div>

            <label for="prodId">ID:</label>

            <input type="text" id="prodId" size="5"/>

            <input type="button" value="Search" onclick="find();" />

            <p id="product" />

        </div>

    </div>

</body>

</html>

运行程序

按下 F5 启动调试程序。网页应该如下图所示：

这不是最好的web设计，但它演示了HTTP服务是可行的。通过在文本框内输入ID就可以通过这个ID获取产品。

如果输入了无效ID，服务器将返回一个HTTP错误：

理解路由

本节解释ASP.NET Web API是如何将URI映射到控制器方法的。详见 Routing in ASP.NET Web API.

对于每一个HTTP消息， ASP.NET Web API 框架通过询问路由表来决定由哪个控制器接收。当新建一个Web API项目时，项目就包含了一个默认的路由，如下所示：

/api/{controller}/{id}

{controller} 和 {id} 是占位符。当框架看到匹配此模式的URI时，它会去找相应的方法来调用，匹配规则如下：

{controller} 与控制器名称匹配。
HTTP 请求方法与方法名匹配。 (此规则只对 GET, POST, PUT, 和 DELETE 请求使用.)
{id}，如果有，与名为id的方法参数匹配。
可能的话，查询参数与参数名称匹配。

基于我们当前的实现，这里是一些示例请求，以及各自的操作。

URI	HTTP 方法	操作
/api/products	GET	GetAllProducts()
/api/products/1	GET	GetProductById(1)
/api/products?category=hardware	GET	GetProductsByCategory("hardware")

在第一个例子中， "products" 与名为 ProductsController 的控制器匹配。由于是一个 GET 请求，所以框架在ProductsController 上去找名字以"Get..."开头的方法。此外，URI不包含可选的 {id} 段，所以框架去找没有参数的方法。ProductsController::GetAllProducts 方法满足所有这些要求。

第二个例子是一样的，除了URI包含了 {id} 部分。因此，框架调用 GetProduct，它有一个名为id的参数。还有，注意URI中值“5”作为id参数传入。框架会基于方法签名，自动将“5"转换为int类型。

这里是一些会导致路由错误的请求：

URI	HTTP 方法	操作
/api/products/	POST	405 Method Not Allowed
/api/users/	GET	404 Not Found
/api/products/abc	GET	400 Bad Request

第一个例子，客户端发送了一个 HTTP POST 请求。框架去找名字以”Post...“开头的方法。但是在ProductsController里根本不存在这样的方法，所以框架返回一个 HTTP 响应，状态405，Method Not Allowed。

对于 /api/users 的请求失败，因为压根就没有名为 UsersController 的控制器。对 api/products/abc 的请求失败，因为id参数是int类型，而 URI 段的"abc" 无法转换为int。

使用 F12 查看 HTTP 请求和响应

当使用 HTTP 服务时，查看HTTP请求和请求消息非常有用。在IE9里通过F12开发者工具就能做到。IE9里，按下F12，打开工具。点击”网络“页签，按下”开始捕获“按钮。回到网页并按F5重新加载网页。IE就会捕获浏览器和服务器间的HTTP流量。”摘要视图“显示一个页面的所有网络流量。

找到相对URI “api/products/” 的条目。选择此条目点击”转到详细视图“。在详细视图里，可以看到请求和响应的标头和正文。比如，如果点击”请求标头“页签，就可以看到客户端在Accept标头里请求了"application/json"。

如果点击”响应正文“标签，可以看到产品列表时如何序列化为JSON的。其它的浏览器也有类似的功能。另一个有用的工具是 Fiddler，一个web 调试代理。你可以用Fiddler来查看HTTP流量，还可以组合HTTP请求，这样你可以对请求中的HTTP标头进行完全控制。

下一步

想查看完整的支持POST, PUT, 和DELETE操作的HTTP服务例子，见：

Web API 不要求一定用 ASP.NET MVC. 其它的选择见：

原文地址：http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/tutorial-your-first-web-api