ASP.NET Web API 心得筆記 (4) 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 專案，專案樣版會建立預設路由給你：

routes.MapHttpRoute( _
    name:="DefaultApi", _
    routeTemplate:="api/{controller}/{id}", _
    defaults:=New With {.id = RouteParameter.Optional} _
)

注意，如果你使用 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
• /api/products/ApplePie

不管如何，下面的 URI 不會符合，因為它遺失 "api" 片段：

• /contacts/1

注意，使用 "api" 在路由裡避免與 ASP.NET MVC 路由衝突。這樣，你能使用 "/contacts" 在 MVC controller，使用 "/api/contacts" 在 Web API controller。當然，如果你不喜歡這種慣例，你可以自行修改預設路由表。

當一個符合的路由發現，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 的參數。

讓我們看個例子，假如你定義以下 controller：

Imports System.Web.Http
Imports System.Net.Http

Public Class ProductsController
    Inherits ApiController

    Sub GetAllProducts()
    End Sub

    Function GetProductById(id As Integer) As IEnumerable(Of Products)
    End Function

    Function DeleteProduct(id As Integer) As HttpResponseMessage
    End Function
End Class

以下有一些可能 HTTP 請求：

Web API Routing and HTTP Method

HTTP Method	URI路徑	Action	參數
GET	/api/products	GetAllProducts	(無)
GET	/api/products/5	GetProductById	5
DELETE	/api/products/5	DeleteProduct	5
POST	/api/products	(無符合)

留意 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 屬性。

例如，以下的 FindProduct 方法會對應至 GET 請求：

<HttpGet>
Function FindProduct(id As Integer) As Products
End Function

允許多個 HTTP 方法在一個 action，或允許 HTTP 方法(GET, POST, PUT, DELETE)以外使用 AcceptVerbs 屬性，取得採用的 HTTP 方法清單。

<AcceptVerbs("GET", "HEAD")>
Function FindProduct(id As Integer) As Products
End Function

' WebDAV 方法
<AcceptVerbs("MKCOL")>
Sub MakeCollection()
End Sub

Action 名稱的路由

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

routes.MapHttpRoute(
    name:="ActionApi",
    routeTemplate:="api/{controller}/{action}/{id}",
    defaults:=New With {.id = RouteParameter.Optional}
)

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

<HttpGet>
Function Details(id As Integer) As String
End Function

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

非 Action

如果要預防一個 action 被呼叫，可以使用 NonAction 屬性。這是一個信號跟 Framework 說此方法不是一個 action 方法。

' 不是 action 方法
<NonAction>
Function GetPrivateData() As String
End Function

參考資料

• Routing in ASP.NET Web API