Code Copied

【译】Web API系列教程(一)——开始使用Web API 2

HTTP的作用不仅仅局限于web页面,它还是一个强力的平台,能够提供一些公开的服务和数据。
HTTP是简单、灵活、无处不在的。几乎任何一个你能想到的平台,都有一个HTTP库,所有HTTP服务可以应用于广泛的不同类型的客户端,包括浏览器、移动设备和传统的桌面应用程序。
ASP.NET Web API是一个用于构建Web API(HTTP Service)并且基于.NET Framework的框架。在本文的教程中,我们将使用Web API来构建一个简单的应用程序。

1. 创建一个Web API项目

在本教程中,我们将创建一个Web API的应用程序,它返回一个产品列表,前端网页使用jQuery来显示结果。

启动Visual Studio,在开始页或者菜单中选择New Project。

在Templates面板,选择Installed Templated并展开Visual C#节点。在Visual C#节点所列举的项目模板中选择Web,然后选择ASP.NET Web Application。给项目起个名字“ProductsApp”,然后点击OK。

SNAGHTML341342

在弹出的New ASP.NET Project对话框中,选择空模板。在“Add folders and core references for”中,选择Web API,点击OK。

SNAGHTML3502bf

你还可以使用"Web API"模板创建一个 Web API 项目(上图中的第1行第4个)。Web API 模板使用 ASP.NET MVC作为API 的帮助页面。
我在本教程中使用空模板,因为我想在没有MVC的情况下使用Web API。
一般情况下,你不需要知道 ASP.NET MVC 也能使用 Web API。

2. 添加一个Model

模型是表示你的应用程序中的数据对象。
ASP.NET Web API 可以自动将模型序列化为JSON、XML或者其他格式,然后将序列化的数据写入到 HTTP 响应消息的正文。
只要客户端可以读取序列化格式,它就可以通过反序列化该对象获取数据。大多数客户端可以解析 XML 或 JSON。
此外,客户���可以通过设置HTTP请求的Accept Header表明它需要哪一种格式的数据。

下面让我们创建一个简单的产品模型。

如果解决方案资源管理器(Solution Explorer)不可见,请在菜单单击View,选择解决方案资源管理器。
在解决方案资源管理器中,右键单击模型文件夹,添加Class。

image

将这个Class命名为“Product”,并添加下列属性:

namespace ProductsApp.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Category { get; set; }
        public decimal Price { get; set; }
    }
}

3. 添加一个Controller

在Web API 中,控制器是处理 HTTP 请求的对象。我们将会添加一个控制器(Controller),可以返回一个产品列表或指定ID的单个产品。

Note:注意如果你曾经使用过ASP.NET MVC,您可能已经熟悉控制器了。
Web API的 控制器类似于 MVC的控制器,但它继承于ApiController,而不是Controller。

在解决方案资源管理器中,右键单击Controllers文件夹,选择添加Controller。

image

在Add Scaffold对话框中,选择Web API Controller – Empty,点击添加。

SNAGHTML9497a0

在Add Controller对话框中,将Controller命名为“ProductsController”,点击添加。

SNAGHTML94e14c

基架(scaffolding)在Controllers文件夹中创建了一个ProductsController.cs的文件。

image

然后在这个文件中添加如下的代码:

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 IHttpActionResult GetProduct(int id)
    {
        var product = products.FirstOrDefault((p) => p.Id == id);
        if (product == null)
        {
            return NotFound();
        }
        return Ok(product);
    }
}

为了保持示例简单,在控制器类中Products存储在一个固定的数组中。当然,在实际应用中,你可能会查询数据库,或使用一些其他外部数据源。

Controller定义了2个返回产品的方法:

  • GetAllProducts方法以列表形式返回所有的产品
  • GetProduct方法通过ID查找一个产品

That's it!现在你有一个可以工作的Web APi了。Controller中的每一个方法至少对应一个URI。

Controller方法 URI
GetAllProducts /api/products
GetProduct /api/product/id


对于GetProduct方法,id是URI的占位符。例如:获取ID为5的Product对应的URI是api/product/5。

4. 用JavaScript或jQuery调用Web API

在本节中,我们将添加一个 HTML 页面,使用 AJAX 调用Web API。我们将使用 jQuery Ajax进行调用,并将结果更新在页面上。

在解决方案资源管理器中,右键选择项目添加一个HTML页面。

image

将这个文件中的所有内容替换成如下的代码:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Product App</title>
</head>
<body>

  <div>
    <h2>All Products</h2>
    <ul id="products" />
  </div>
  <div>
    <h2>Search by ID</h2>
    <input type="text" id="prodId" size="5" />
    <input type="button" value="Search" onclick="find();" />
    <p id="product" />
  </div>

  <script src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.min.js"></script>
  <script>
    var uri = 'api/products';

    $(document).ready(function () {
      // Send an AJAX request
      $.getJSON(uri)
          .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
              // Add a list item for the product.
              $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
          });
    });

    function formatItem(item) {
      return item.Name + ': $' + item.Price;
    }

    function find() {
      var id = $('#prodId').val();
      $.getJSON(uri + '/' + id)
          .done(function (data) {
            $('#product').text(formatItem(data));
          })
          .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
          });
    }
  </script>
</body>
</html>

有几种方法来得到 jQuery,在此示例中,我使用 Microsoft Ajax CDN。你也可以从 http://jquery.com/ 下载,如果使用ASP.NET"Web API"项目模板创建项目将会包含jQuery。

获取Products列表

若要获取Product列表,则发送请求到/api/products

这个过程可以阐述为如下步骤

  1. jQuery getJSON函数发送一个 AJAX 请求,响应结果包含一个JSON对象数组。
  2. done方法在请求成功时指定一个回调函数。
  3. 在回调函数中,我们在DOM中更新Product信息。
$(document).ready(function () {
    // Send an AJAX request
    $.getJSON(apiUrl)
        .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
                // Add a list item for the product.
                $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
        });
});

根据ID获取Product

若要通过ID获取Product,则发送请求到”/api/products/id”,id参数就是Product的ID。

function find() {
    var id = $('#prodId').val();
    $.getJSON(apiUrl + '/' + id)
        .done(function (data) {
            $('#product').text(formatItem(data));
        })
        .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
        });
}

我们仍然使用getJSON 发送 AJAX 请求,但这次我们把 ID 放在请求的URI中。
来自此请求的响应是单个Product的JSON数据对象。

5. 运行应用程序

按 F5 启动调试应用程序。Web 页应该如下所示:

SNAGHTML1debc5

要根据ID获取Product,输入ID并点击Search按钮:

SNAGHTML221583

如果输入了无效的ID,服务器将返回HTTP错误

SNAGHTML21a14e

6. 用F12来查看HTTP请求和响应

当你正在运行一个HTTP Service时,能够看到HTTP的请求和响应信息是非常有用的。在Chrome中,你可以通过F12运行开发者工具(developer tools),然后点击Network选项卡。
现在按F5刷新页面,在Network选项卡中我们能够看到请求的信息。

SNAGHTML287ff9

找到/api/products,单机此项跳转到详细信息,在详细信息中可以看到请求头(Request Header)和返回头(Response Header)的信息。

SNAGHTML2db876