随着项目的复杂度越来越高，各种第三方系统的数据交互也越来越频繁，不可避免的就要用到Web API接口，这里Web API是一个比较宽泛的概念。本文提到Web API特指ASP.NET Web API。本文以一些简单的小例子，简述ASP.NET Web API的相关基础知识，仅供学习分享使用，如有不足之处，还请指正。
什么是RESTful?
REST全称是Representational State Transfer，中文意思是表述状态转移。REST本身并没有创造新的技术、组件或服务，而隐藏在RESTful背后的理念就是使用Web的现有特征和能力， 更好地使用现有Web标准中的一些准则和约束。 如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。对于RESTful，原作者是这样描述的【我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。】
综合上面的解释，我们总结一下什么是RESTful架构：
- 每一个URI代表一种资源；
- 客户端和服务器之间，传递这种资源的某种表现层；
- 客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。
什么是Web API?
ASP.NET Web API基于C#构建安全的符合REST风格的API。通过ASP.NET Web API，可以快速创建在各个客户端进行调用的服务，包括Web浏览器端和移动端等。如下所示：
为什么要用Web API?
ASP.NET Web API是一个框架，可以很容易构建达成了广泛的HTTP服务客户端，包括浏览器和移动设备。是构建RESTful应用程序的理想平台的.NET框架。在系统架构中的地位，如下所示：
创建ASP.NET Web API项目
文件--新建--项目 打开【创建新项目】窗口，然后选择【ASP.NET Web应用程序（.NET Framework）】，点击下一步，如下所示：
进入【配置新项目】窗口，输入项目名称，选择项目保存路径，然后点击【创建】，如下所示：
进入【创建新的ASP.NET Web应用程序】创建，选择【空】，然后添加【MVC,Web API】核心引用，然后点击【创建】如下所示：
稍等片刻，项目即创建成功，目录结构如下所示：
- App_Start目录下RouteConfig.cs为MVC核心引用，主要用于注册MVC路由配置
- App_Start目录下WebApiConfig.cs为Web API的核心引用，主要用于注册Web API的路由配置。
- 默认创建了Controllers，Models，Views三个目录，分别用于存放三层架构各自的内容。
创建第一个接口
在Controllers文件夹，右键--添加--Web API控制器类，如下所示：
然后输入控制器名称，以Controller结尾，点击【确定】，如下所示：
通过模板创建的控制器，自动添加了示例代码，且默认继承ApiController，如下所示：
namespace WebApiDemo.Controllers { public class StudentController : ApiController { // GET api/<controller> public IEnumerable<string> Get() { return new string[] { "value1", "value2" }; } // GET api/<controller>/5 public string Get(int id) { return "value"; } // POST api/<controller> public void Post([FromBody] string value) { } // PUT api/<controller>/5 public void Put(int id, [FromBody] string value) { } // DELETE api/<controller>/5 public void Delete(int id) { } } }
定制API
为了进行测试，首先新建Model类Student，如下所示：
using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Threading.Tasks; namespace WebApiDemo.Models { public class Student { public int Id { get; set; } public string Name { get; set; } public int Age { get; set; } public bool Sex { get; set; } } }
1. GET方式
在StudentController中，引用Models命名空间中的Student模型，修改Get方法，如下所示：
默认情况下，WebApi模板自动创建了两个Get方法，一个无参，一个有参，分别返回列表和具体实例，进行调整，返回Student数据，如下所示：
// GET api/<controller> public IEnumerable<Student> Get() { return new Student[] { new Student() { Id=1, Name="Alan.hsiang", Age=20, Sex=true }, new Student() { Id=2, Name="Json.hsiang", Age=18, Sex=false } }; } // GET api/<controller>/5 public Student Get(int id) { return new Student() { Id = 1, Name = "Alan.hsiang", Age = 20, Sex = true }; }
然后运行VisualStudio，默认端口为44311，通过PostMan进行测试。
不带参数，返回Student列表。如下所示：
带参数的，返回某个具体的Student实例，id可以通过api/Controller/id的方式进行传递。如下所示：
2. POST方式
POST方法主要是通过body表单的方式进行提交，本例修改自带的代码，接收入参Student实例，返回Student字符串，如下所示：
// POST api/<controller> public string Post([FromBody] Student value) { return string.Format("学生的ID={0}，姓名={1}，年龄={2}，性别={3}",value.Id,value.Name,value.Age,value.Sex); }
通过Postman，进行访问，访问方式选择POST，Body选择raw，数据格式选择JSON，如下所示：
3. PUT方式
PUT方式一般用于修改数据，本例为了测试，返回接收的ID，如下所示：
// PUT api/<controller>/5 public int Put(int id, [FromBody] string value) { //为了测试，返回接收到的id return id; }
通过Postman进行测试，请求方式选择PUT，Body内容如果只有一个string类型参数，则参数名为空，如下所示：
4. DELETE方式
DELETE方式一般用于删除数据，本例为了测试，返回一个字符串，如下所示：
// DELETE api/<controller>/5 public string Delete(int id) { return string.Format("Id={0} 已删除", id); }
通过Postman进行测试，请求方式选择DELETE，如下所示：
总结
通过以上示例的测试，总结如下：
- 访问路径，符合RESTful的风格，通过请求方式进行区分具体的功能，如下所示：
- GET 请求列表：https://localhost:44311/api/Student
- GET 请求单一实例：https://localhost:44311/api/Student/1
- POST请求：https://localhost:44311/api/Student/
- PUT方式：https://localhost:44311/api/Student/3
- DELETE方式：https://localhost:44311/api/Student/4
- 请求数据格式：
- GET方式，一般采用URL的方式进行传递参数
- POST，PUT，DELETE方式，采用body传参，格式一般文JSON。
通过以上总结，发现WebAPI与RESTful风格架构不谋而合。
同一方式多个参数
在本例中，如果有多个GET方式的请求方法，且参数格式，个数不同，应该如何匹配，如下所示：
// GET api/<controller> public IEnumerable<Student> Get() { return new Student[] { new Student() { Id=1, Name="Alan.hsiang", Age=20, Sex=true }, new Student() { Id=2, Name="Json.hsiang", Age=18, Sex=false } }; } // GET api/<controller>/5 public Student Get(int id) { return new Student() { Id = 1, Name = "Alan.hsiang", Age = 20, Sex = true }; } // GET api/<controller>/5?name=aabbcc public Student Get(int id,string name) { return new Student() { Id = id, Name = name, Age = 22, Sex = true }; }
前两种方式以通过Postman进行测试，现在测试第三种方式，如下所示：
同一方式，不同名称
通过以上示例，可以看出方法名和请求方式是一一对应的，那如果方法名和请求方式不一致呢？
首先增加GetStudent方式，为了区分，在返回的Name值分别写了0和1，如下所示：
// GET api/<controller>/5?name=aabbcc public Student Get(int id,string name) { return new Student() { Id = id, Name = name+"---0", Age = 22, Sex = true }; } public Student GetStudent(int id, string name) { return new Student() { Id = id, Name = name+"---1", Age = 22, Sex = true }; }
打开Postman进行测试，直接报错，称找到了两个符合格式的资源的，如下所示：
以上问题，通过查看WebApiConfig.cs即可发现，WebApi注入的routeTemplate是api/{controller}/{id}，没有action做区分，此处和MVC不同。WebApi注册默认路由模板，如下所示：
namespace WebApiDemo { public static class WebApiConfig { public static void Register(HttpConfiguration config) { // Web API 配置和服务 // Web API 路由 config.MapHttpAttributeRoutes(); config.Routes.MapHttpRoute( name: "DefaultApi", routeTemplate: "api/{controller}/{id}", defaults: new { id = RouteParameter.Optional } ); } } }
Route特性
为了解决两个访问方式相同，参数相同，但是方法名不同，会导致获取报错的问题，WepApi引入了路由特性，如下所示：
[Route("api/Student/QueryStudent/{id}")] [HttpGet] public Student QueryStudent(int id, string name) { return new Student() { Id = id, Name = name + "---1", Age = 22, Sex = true }; }
如下，通过Postman进行访问，则可以正常访问。默认访问Get(int id,string name)
通过路由特性，访问/api/Student/QueryStudent/4?name=HEX，如下所示：
路由前缀
通过路由特性，完美解决了一个Controller，同一种方式，同时访问两个不同的方法的问题。但是如果每一个路由特性都写全称，也会很繁琐，且容易出错，所以路由前缀，应运而生。
路由前缀修饰Controller，路由特性修饰Action，如下所示：
namespace WebApiDemo.Controllers { [RoutePrefix("api/Teacher")] public class TeacherController : ApiController { public string Get(int id, string name) { return string.Format("[Get]正在查找的老师id={0}，姓名={1}", id, name); } [Route("query/{id}")] [HttpGet] public string QueryTeacher(int id, string name) { return string.Format("[Query]正在查找的老师id={0}，姓名={1}", id, name); } } }
这样在访问时，即可区分，默认访问Get方法，如下所示：
通过路由特性，访问Query方法，如下所示：
备注
以上就是ASP.NET Web API基础知识的简单介绍，本文旨在抛砖引玉，共同学习，一起进步。
清平调·其一 李白 〔唐代〕
云想衣裳花想容，春风拂槛露华浓。若非群玉山头见，会向瑶台月下逢。
清平调·其二 李白 〔唐代〕
一枝秾艳露凝香，云雨巫山枉断肠。借问汉宫谁得似，可怜飞燕倚新妆。
清平调·其三 李白 〔唐代〕
名花倾国两相欢，长得君王带笑看。解释春风无限恨，沉香亭北倚阑干。
