ASP.NET Web API入門介紹（一）

隨着項目的復雜度越來越高，各種第三方系統的數據交互也越來越頻繁，不可避免的就要用到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架構：

1. 每一個URI代表一種資源；
2. 客戶端和服務器之間，傳遞這種資源的某種表現層；
3. 客戶端通過四個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基礎知識的簡單介紹，本文旨在拋磚引玉，共同學習，一起進步。

清平調·其一              李白 〔唐代〕

雲想衣裳花想容，春風拂檻露華濃。若非群玉山頭見，會向瑤台月下逢。

清平調·其二             李白 〔唐代〕

一枝穠艷露凝香，雲雨巫山枉斷腸。借問漢宮誰得似，可憐飛燕倚新妝。

清平調·其三             李白 〔唐代〕

名花傾國兩相歡，長得君王帶笑看。解釋春風無限恨，沉香亭北倚闌干。