Contact Manager Web API 樣本[2] Web API Routing

連絡人管理器web API是一個Asp.net web api樣本程式，示範了通過ASP.NET Web API 公開聯絡資訊,並允許您添加和刪除連絡人，樣本地址http://code.msdn.microsoft.com/Contact-Manager-Web-API-0e8e373d。 Contact Manager Web API 樣本[1]CRUD 操作 已經做了一個基本的介紹，本文主要介紹Web API Routing。

如果你已經熟悉 ASP.NET MVC，你會發現 Web API Routing(路由)與 MVC 非常類似。主要差異在 Web API 使用 HTTP Method ( GET, POST, PUT, DELETE ...) 而不是使用 URI 路徑來選擇 Action。你也可以在 Web API 裡使用 MVC 樣式的路由。以下討論專註在 Web API 且可以沒有 ASP.MVC 基礎。

ROUTING TABLES, 路由表

在 ASP.NET Web API，一個 controller 是一個 class(類) 以處理 HTTP 要求(requests)。在 controller 裡所有的公開方法(public  methods)都稱為 Action方法 或簡稱 Action。當 Web API Framework 接收到一個請求，它路由請求到一個 Action。
Framework 會使用路由表(Routing Table)，決定那一個 Action 會被調用。如果你在 ASP.NET 裡使用 Web API，路由表會定義在 Global.asax 檔案中。預設使用 Visual Studio 去新增一個 Web API 項目，項目樣版會建立預設路由給你：

config.Routes.MapHttpRoute(
             "Default", // Route name
             "{controller}/{id}/{ext}", // URL with parameters
             new { id = RouteParameter.Optional, ext = RouteParameter.Optional } // Parameter defaults
         );

注意，如果你使用 self-host Web API，你必須在 HttpSelfHostConfiguration對象 上直接設定路由表。

每個實體(entry)在路由表裡都包含一個路由樣板(route template)。Web API 的路由樣板預設是 "api/{controller}/{id}"，此樣板裡，"api" 是文字路徑片段，{controller} 和 {id} 是定位參數。
當 Web API Framework 接收到一個 HTTP 要求，它會去嘗試比對 URI 對路由表的路由樣板之一， 如果沒有符合的路由，Client 會收到一個 404 錯誤。例如，以下 URI 會符合預設路由：

· /api/contacts

· /api/contacts/1

當發現一個符合的路由，Web API 會選擇 controller 與 action：

· 尋找 controller，Web API 新增 "Controller" 到 {controller} 變數的值。

· 尋找 action，Web API 查看 HTTP 方法，然後查看 action，哪一個名稱的開始與是 HTTP 方法名稱。例如，一個 GET 請求，Web API 會查看那一個 action 是以 "Get..."  開頭，像是 "GetContact" 或 "GetAllContacts"。此慣例使用在 GET, POST, PUT, DELETE 方法。你也能在 controller 裡使用屬性(attributes)去啟用其他 HTTP 方法。

· 在路由樣板裡其他定位變數，像是 {id}，會對應至 action 的參數。

以下有一些可能 HTTP 要求：

Web API Routing and HTTP Method
HTTP Method	URI路徑	Action	參數
GET	/api/contacts	GetAllContacts	(無)
GET	/api/contacts/5	GetContactById	5
DELETE	/api/contacts/5	DeleteContact	5
POST	/api/contacts	(無符合)

留意 URI 的 {id} 段落，如果存在，會對應到 action 裡的 id 參數。上述範例， controller 定義了兩個 GET 方法，一個有 id 參數一個無 id 參數。另外，POST 請求會失敗，因為在 controller 裡沒有定義 "Post..." 方法。

路由參數, ROUTING VARIATIONS

接下來我們討論路由參數。

HTTP 方法, HTTP Methods

Web API 使用HTTP 方法的名稱慣例(naming convention)來替代。你也可以明確在 action 方法上指定使用 HttpGet, HttpPost, HttpPut, HttpDelete 屬性。
例如，以下的 Get 方法會對應至 GET 請求：

       [HttpGet]
      public HttpResponseMessage<Contact> Get(int id)
      {
         ……

      }

Action 名稱的路由

在預設路由模板，Web API 使用 HTTP 方法來選擇 action。不管如何，你也能建立一個 URI 含有 action 名稱的路由。

config.Routes.MapHttpRoute(
                "Default", // Route name
                "/api/{controller}/{action}/{id}", // URL with parameters
                new { id = RouteParameter.Optional} // Parameter defaults
            );

此路由樣板，在 controller 裡的 action 方法會與 {action} 參數對應。使用此種路由樣式，你必須明確指定允許屬性在 HTTP 方法。例如，在 controller 裡有一個 Details 方法：

       [HttpGet]
      public HttpResponseMessage<Contact> Details(int id)
      {

      }
一個 "/api/contacts/details/1" 的 GET 請求將會對應至 Details 方法。這種路由樣式非常類似 ASP.NET MVC，或是接近一個 RPC-style API。在一個 RESTful API，你應該避免在 URI 使用動詞(verbs)，因為 URI 應該是定義資源而不是action。

非 Action

如果要預防一個 ACTION 被呼叫，可以使用 NONACTION 屬性。這是一個訊號跟 FRAMEWORK 說此方法不是一個 ACTION 方法。

      [NonAction]
      public Contact GetPrivateContact(int id)
      {

            ……

      }

參考資料

• Routing in ASP.NET Web API
• Attribute based routing in ASP.NET Web API
• Domain based routing with ASP.NET Web API
• Magical Web API action selector – HTTP-verb and action name dispatching in a single controller