初识 Web API
一、 Web API简介
XML：可扩展标记语言，可以用来标记数据、定义数据类型，是一种允许用户对自己的标记语言进行定义的源语言。格式统一、跨平台和编程语言，业界公认的标准，非常适合 Web 传输。XML文件庞大，文件格式复杂，传输占带宽；服务器端和客户端都需要花费大量代码来解析XML，导致服务器端和客户端代码变得异常复杂且不易维护；客户端不同浏览器之间解析XML的方式不一致，需要重复编写很多代码，花费较多的资源和时间。
JSON：一种轻量级的数据交换格式，具有良好的可读和便于快速编写的特性，在不同平台之间进行数据交换，为理想的数据交换语言。数据格式比较简单，具有数组和字典的特征，易于读写，格式都是压缩的，占用带宽小，传输速度快；易于解析，客户端JavaScript可以简单的通过eval()进行JSON数据的读取；支持多种语言，便于服务器端的解析。
- 1. WebAPI概念
API（Application Programming Interface,应用程序编程接口）
Web API ：基于互联网的应用程序编程接口（使用HTTP协议，80端口进行访问和交互），互联网的服务提供者。
ASP.NET Web API 支持让你能够轻松地创建功能强大的 Web API 程序接口，可以从范围广泛的客户端 （包括使用 JavaScript 的浏览器，移动客户端，本机应用程序等）访问。构建一个基于 HTTP 协议的 Client/ Server 模式的服务架构。Web API最重要的是可以构建面向各种客户端的服务。
在MVC中增加了Web API，Web API和WebService一样都可以让你创建一个HTTP服务，可以简单理解为基于REST风格的WebService，但是还是有很多不同点。如WebService基于XML，Web API基于JSON。
Web API在ASP.NET完整框架中地位
在图上可以看出来，Web API 与SignalR一起同为构建Service的框架。Web API负责构建http常规服务，而SingalR主要负责的是构建实时服务，例如股票，聊天室，在线游戏等实时性要求比较高的服务
SignaIR是ASP.NET下的一个库，可用于web项目中的实时通信，可以让服务器端代码向客户端推送内容，而不是等待客户端请求数据。
- 2. Web API和Web Service的区别
Web API
l 这是一个简单的构建HTTP服务的新框架。
l 在.NET平台上Web API是一个开源的、理想的、构建REST-ful服务的技术。
l 他也支持MVC的特征，像路由、控制器、Action、Filter、模型绑定、控制反转（IOC）或依赖注入（DI），单元测试。这些可以使程序更简单、更健壮。
l 他可以部署在应用程序和IIS上。
l 这是一个轻量级的框架，并且对限制带宽的设备，比如智能手机等支持的很好。
l 返回值可以被Web API的MediaTypeFormatter转换成JSON、XML 或者任何你想转换的格式
Web Service
l 它是基于SOAP协议的，数据格式是XML。
l 只支持HTTP协议，只能部署在IIS上。
l 它不是开源的，但可以被任意一个了解XML的人使用。
- 3. Web API 与MVC的区别
l MVC主要用来构建网站，既关心数据也关心页面展示，而Web API只关注数据
l Web API支持格式协商，客户端可以通过Accept header通知服务器期望的格式
l Web API支持Self Host，MVC目前不支持
l Web API通过不同的http verb表达不同的动作(CRUD)，MVC则通过Action名字表达动作
l Web API内建于ASP.NET System.Web.Http命名空间下，MVC位于System.Web.Mvc命名空间下，因此model binding/filter/routing等功能有所不同
l 最后，Web API非常适合构建移动客户端服务
- 4. 什么地方需要用Web API
当你遇到以下这些情况的时候，就可以考虑使用Web API了。
l 需要Web Service但是不需要SOAP
l 需要在已有的WCF服务基础上建立non-soap-based http服务
l 只想发布一些简单的Http服务，不想使用相对复杂的WCF配置
l 发布的服务可能会被带宽受限的设备访问
l 希望使用开源框架，关键时候可以自己调试或者自定义一下框架
二、 创建Web API
- 1. 使用Web API模板创建Web API，项目结构如下图
l 新生成的WebAPI项目和典型的MVC项目一样，包含主要的Models、Views、Controllers等文件夹和Global.asax文件。Area在项目中可以称之为区域，每个Area代表应用程序的不同功能模块，Area 使每个功能模块都有各自的文件夹，文件夹中有自己的Controller、View和Model。
l Views对于WebAPI来说没有太大的用途。
l Models中的Model主要用于保存Service和Client交互的对象，这些对象默认情况下会被转换为JSON格式的数据进行传输。
l Controllers中的Controller对应于WebService来说是一个Resource，用于提供服务。和普通的MVC一样。
l Global.asax用于配置路由规则
项目会自动添加一个 Web API 控制器，在 Controllers 目录中的 ValuesController.cs 文件，提供了Web API 标准访问接口示例，并附带访问地址。
运行项目。项目模板自动生成的API开发文档
API接口文档，这里显示了控制器名称，接口地址，以及接口描述信息
- 2. Web API的主要功能
l 请求的回复通过Http Status Code表达不同含义（404，403，200，500等），并且客户端可以通过Accept Header来与服务器协商格式，例如你希望服务器返回JSON格式还是XML格式。
200 请求已成功
400 语义有误，当前请求无法被服务器理解；请求参数有误
403 服务器已经理解请求，但是拒绝执行它
404 请求失败，请求所希望得到的资源未被在服务器上发现
500 服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理
l MVC WebAPI中的Controllers和普通MVC的Controllers类似，但不再继承于Controller，而改为继承API的ApiController。
l MVC WebAPI 基于 Http 动作 (GET, POST, PUT, DELETE) 实现 CRUD (create, retrieve, update, delete) 操作，通过不同的 HTTP 动作表达不同的含义，这样就不需要暴露多个 API 来支持这些基本操作。
l 一个Controller默认包含5个Action。分别对应对于数据表的5个操作
URL路由匹配表
|
URL |
HttpMethod |
对应的Action名 |
|
api/User |
GET |
Get() |
|
api/User/1 |
GET |
Get(int id) |
|
api/User |
POST |
Post([FromBody]string value) |
|
api/User/1 |
DELETE |
Delete(int id) |
|
api/User/22 |
PUT |
Put(int id, [FromBody]string value) |
路由规则默认情况下，模板自带了两个路由规则，分别对应于Web API和普通MVC的Web请求，默认的Web API路由规则如下。
routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
);
可以看到，默认路由使用的固定的API作为URI的先导，按照微软官方的说法，用于区分普通Web调用和Web Service的调用路径：
Web API和MVC里面的路由有点不同，Web API的默认路由是通过HTTP的方法（GET / POST / PUT / DELETE）去匹配对应的Action，也就是说Web API 的默认路由并不需要指定Action的名称。
三、 API文档
Web API模板创建项目，模板中会自动提供一个HelpPage接口文档，方便我们很方便的查看文档信息。但是默认的接口文档使用过程中还是有很多不方便的地方，例如很多的英文描述，以及没有解释接口作用，参数没有介绍等，都会给阅读者带来各种障碍，导致需要额外的人工沟通去解释如何使用
- 1. 设置接口描述信息
在平时编写程序代码时，我们可以在方法定义代码上一行输入“///”符号，来给这段代码写注释，方便以后阅读。
HelpPage文档工具是可以自动将“///”的注释信息提取到接口文档中用来解释接口用途，参数描述信息的。
- 2. 配置HelpPage文档，显示输出XML文件，启用自定义接口描述信息显示
1) 在解决方案资源管理器中，选择当前项目点击鼠标右键 -> 属性 -> 选择生成，在页面下部找到输出， 在其中进行如下设置，勾选 XML 文档文件，并设置名称，名称可以自定义，但是注意要与以后使用时名称一致
2) 打开 \Areas\HelpPage\App_Start\HelpPageConfig.cs 文件，取消如下代码注释，并修改路径与 上条 XML 文档文件设置一致。
config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/bin/Qin_WebAPI_HelloWorld.xml")));
3) 在 Web API 控制器中编写方法描述信息
4) 运行测试
- 3. 修改接口文档视图文件，优化界面显示
在 /Areas/HelpPage 目录中包含有 Web API 接口文档页面的 MVC 项目 , 在 Views 子目录中，包含了网 站里面的所有视图模板。我们可以在这里找到我们需要修改的内容。
l Views/Help/Index.cshtml：这是 Web API接口文档的首页模板，这里可修改文档标题、介绍信息等。
l Views/Help/DisplayTemplates/ApiGroup.cshtml：这是接口组的显示模板，这里可修改显示接口的表格的标题等。
l Views/Help/DisplayTemplates/HelpPageApiModel.cshtml：这是某接口具体用法的显示模板，这里可修改请求参数、返回值资源的描述等。
四、 Web API控制器中的Action方法有如下几种返回类型：
|
返回类型 |
Web API创建HTTP响应消息的机制 |
|
void |
返回HTTP状态码204(无内容) |
|
HttpResponseMessage |
直接转换成HTTP响应消息 |
|
IHttpActionResult |
调用接口的ExecuteAsync方法创建一个HttpResponseMessage对象，然后转换成HTTP响应消息 |
|
其它类型 |
把序列化后的返回值写入响应正文，并且返回HTTP状态码200(OK) |
- 1. Void
void声明的接口，在请求成功的时候得不到返回值，而且会返回http的状态码为204，表示没有返回值
- 2. HttpResponseMessage
HttpResponseMessage这个对象，表示向客户端返回一个http响应的消息对象（包含http状态码和需要返回客户端的消息）。这个对象也有它独特的使用场景：需要向客户端返回HttpResponse时就要用到这个对象。
- 3. IHttpActionResult
IHttpActionResult是WebApi最常用的一种返回值类型，常用的方式有：Json(T content)、Ok()、 Ok(T content)、NotFound()、Content(HttpStatusCode statusCode, T value)、BadRequest()、Redirect(string location)、StatusCode(HttpStatusCode statusCode)等
l 返回 Json(T content)，返回的是JsonResult对象，如return Json<List<userinfo>>(list);；也可以使用dynamic来返回一个对象，如：return Json<dynamic>(new { AA = "a", BB = "b" });
l 如果返回Ok()，就表示不向客户端返回任何信息，只告诉客户端请求成功，如return Ok();；Ok(T content)向客户端返回一个成功的对象，如：return Ok(result);。
l NotFound()方法会返回一个404的错误到客户端，如：return NotFound()；
l Content(HttpStatusCode statusCode, T value)，向客户端返回值和http状态码，如：return Content<string>(HttpStatusCode.OK, "OK");。
l BadRequest() 向客户端返回400的http错误，如：return BadRequest();
l Redirect(string location) 将请求重定向到其他地方，如：
return Redirect("http://localhost:7408/api/Values/getJson1");
l StatusCode(HttpStatusCode statusCode)：方法中传入一个HttpStatusCode枚举类型，这里面提供HTTP协议所有的状态码。
- 4. 其它类型
你也可以将webapi的接口和普通方法一样，返回任意的类型，WebApi会自动序列化你自定义任何返回类型，然后将序列化的值写到响应正文里，状态码统一返回200。
基于上面几种不同的返回类型，Web API创建HTTP响应消息的机制也不同。