[ASP.NET MVC 小牛之路]18 - Web API

原文:[ASP.NET MVC 小牛之路]18 - Web APIWeb API 是ASP.NET平台新加的一个特性，它可以简单快速地创建Web服务为HTTP客户端提供API。Web API 使用的基础库是和一般的MVC框架一样的，但Web API并不是MVC框架的一部分，微软把Web API相关的类从 System.Web.Mvc 命名空间下提取了出来放在 System.Web.Http 命名空间下。这种理念是把 Web API 作为ASP.NET 平台的核心之一，以使Web API能使用在其他的Web应用中，或作为一个独立的服务引擎。本文将先带大家理解Web API，再教大家在MVC中使用Web API。

理解 REST 和 RESTful Web API

为了更好的理解Web API，先带大家了解一下 REST 和 RESTful Web API。以下内容大多来自维基百科。

REST（全名：Representational State Transfer），中文翻译是表征状态转移（也有叫表述性状态转移），是Roy Fielding博士在2000年他的博士论文中提出来的一种软件架构风格。

REST 从资源的角度来观察整个网络，分布在各处的资源由URI确定，而客户端的应用通过URI来获取资源的表征。获得这些表征致使这些应用程序转变了其状态。随着不断获取资源的表征，客户端应用不断地在转变着其状态，所谓表征状态转移（Representational State Transfer）。

目前使用Web服务的三种主流的方式是：远程过程调用（RPC），面向服务架构（SOA）以及表征性状态转移（REST），其中REST模式的Web服务与复杂的SOA和RPC对比来讲显的更加简洁，越来越多的web服务开始采用REST风格设计和实现。

需要注意的是，REST是设计风格而不是标准，但REST设计风格常基于使用HTTP，URI，和XML以及HTML这些现有的广泛流行的协议和标准。REST设计风格有如下要点：

资源是由URI来指定。

对资源的操作包括获取、创建、修改和删除资源，这些操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法。

通过操作资源的表现形式来操作资源。

资源的表现形式则是XML或HTML，取决于读者是机器还是人，是消费web服务的客户软件还是web浏览器。当然也可以是任何其他的格式，如JSON。

另外，使用REST需要满足一些要求，如客户端和服务器结构、连接协议具有无状态性、能够利用Cache机制增进性能等。

RESTful Web API（也称为RESTful Web服务）是一个使用HTTP并遵循REST原则的Web服务。它从以下请求资源的三个方面进行定义：

URI，比如：http://example.com/resources/。

Web服务接受与返回的互联网媒体类型，比如：JSON，XML ，YAML 等。

Web服务在该资源上所支持的一系列请求方法（比如：POST，GET，PUT或DELETE）。

本文要讲的ASP.NET Web API 就是RESTful Web API的一种。下表列出了在实现 RESTful Web API 时HTTP请求方法的典型用途：

function selectView(view) {
$('.display').not('#' + view + "Display").hide();
$('#' + view + "Display").show();
}
function getData() {
$.ajax({
type: "GET",
url: "/api/reservation",
success: function (data) {
$('#tableBody').empty();
for (var i = 0; i < data.length; i++) {
$('#tableBody').append('<tr><td><input id="id" name="id" type="radio"'
+ 'value="' + data[i].ReservationId + '" /></td>'
+ '<td>' + data[i].ClientName + '</td>'
+ '<td>' + data[i].Location + '</td></tr>');
}
$('input:radio')[0].checked = "checked";
selectView("summary");
}
});
}
$(document).ready(function () {
selectView("summary");
getData();
$("button").click(function (e) {
var selectedRadio = $('input:radio:checked')
switch (e.target.id) {
case "refresh":
getData();
break;
case "delete":
break;
case "add":
selectView("add");
break;
case "edit":
selectView("edit");
break;
case "submitEdit":
break;
}
});
});

Index.js
我们定义了三个方法。第一个 selectView 方法用于控制div的显示和隐藏。第二个 getData 方法使用jQuery Ajax通过GET请求/api/reservation URL，并将返回的JSON数据填充到summaryDisplay的table中。第三个是jQuery的ready函数，在页面内容加载完成时执行。这时的效果如下：







接下来一步一步完美编辑、保存和删除的功能。添加“编辑”功能代码如下：

...
case "edit":
    $.ajax({
type: "GET",
url: "/api/reservation/" + selectedRadio.attr('value'),
success: function (data) {
$('#editReservationId').val(data.ReservationId);
$('#editClientName').val(data.ClientName);
$('#editLocation').val(data.Location);
selectView("edit");
}
});
    break;
...

当用户点击编辑时，先会取得radio button的value值，并以此组成一个URL（如/api/reservation/1），HTTP请求方式(GET)和URL将使API Controller调用 GetReservation 方法获取一个Reservation对象的JSON，并将其填充到editDisplay的文本框中。效果如下：





下面再完善一下删除和保存功能。代码如下：

...
case "delete":
    $.ajax({
type: "DELETE",
url: "/api/reservation/" + selectedRadio.attr('value'),
success: function (data) {
selectedRadio.closest('tr').remove();
}
});
break;
...
case "submitEdit":
    $.ajax({
type: "PUT",
url: "/api/reservation/" + selectedRadio.attr('value'),
data: $('#editForm').serialize(),
success: function (result) {
if (result) {
var cells = selectedRadio.closest('tr').children();
cells[1].innerText = $('#editClientName').val();
cells[2].innerText = $('#editLocation').val();
selectView("summary");
}
}
});
break;
...

根据Ajax的DELETE请求，API Controller将调用 DeleteReservation 将选中的Reservation对象从集合中删除。同样，根据PUT请求API Controller 将调用PutReservation方法。

最后完善一下添加功能，该ajax请求使用的是 Unobtrusive Ajax，修改 Index.cshtml 如下：

...
<h4>Add New Reservation</h4>
@{
AjaxOptions addAjaxOpts = new AjaxOptions {
OnSuccess = "getData",
Url = "/api/reservation"
};
}
@using (Ajax.BeginForm(addAjaxOpts)) {
@Html.Hidden("ReservationId", 0)
<p><label>Name:</label>@Html.Editor("ClientName")</p>
<p><label>Location:</label>@Html.Editor("Location")</p>
<button type="submit">Submit</button>
}
...

Ajax.BeginForm生成的表单默认使用的是POST请求，相应的 API Controller将调用PostReservation 方法添加Reservation对象。效果如下：





通过这个完整的示例我们可以看到，熟悉MVC后，使用Web API也非常简单，操作上基本和MVC类似，主要的不同体现在 ApiController 和 Action方法的匹配上。

参考：《Pro ASP.NET MVC 4 4th Edition》