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

ASP.NET Web API 心得筆記 (3) CRUD 操作之後端程式

CURD 是 "Create, Read, Update, Delete" (新增、讀取、異動、刪除) 的簡寫,這四個動作是資料庫基本操作。許多的 HTTP Service 也能透過 REST 或 REST-like API 來進行 CRUD 操作。

以下會進行一個非常簡單的連絡人管理。透過以下方法來提供服務。

Web API CRUD 方法說明
Action說明HTTP方法URI關連
取得所有連絡人清單GET/api/contacts
透過 id 取得連絡人資料GET/api/contacts/id
新增一位連絡人POST/api/contacts
更新連絡人資料PUT/api/contacts/id
刪除連絡人資料DELETE/api/contacts/id

由上表中,我們可以很清楚看到,有兩種資源類型( resource types):

URI 資源類型
URI說明
/api/contacts列出所有連絡人
/api/contacts/id一位連絡人

HTTP 方法


HTTP 主要方法 (GET, PUT, POST, DELETE) 能對應到 CURD 操作:
  • GET 接收及顯示。GET 在伺服器應該沒有副作用。
  • PUT 更新。PUT 也能拿來"新增"使用,如果伺服器允許 Client 去指定新的 URI。那範例的連絡人管理將不允許使用 PUT 來新增。
  • POST 新增。伺服器會給 URI 分配新物件,然後返回此 URI 作為回應訊息的一部分。
  • DELETE 刪除

ps. 現在開啟前一篇的 HelloWebAPI 專案。相關步驟不再重覆。

Tool - 製作安裝或部署檔超強工具 Advenced Installer

進入主題前,我們先看幾張圖片:

Visual Studio 2010 安裝和部署專案之一
圖一:Visual Studio 2010 安裝和部署專案之一
Visual Studio 安裝和部署專案之二
圖二:Visual Studio 安裝和部署專案之二
Visual Studio 11 Beta 安裝和部署專案
圖三:Visual Studio 11 Beta 安裝和部署專案
之前寫過幾篇「ASP.NET Web網站部署」都裡介紹的就是圖一與圖二,在圖三之中很明顯,我們看不到 Visual Studio Installer,不見了。還有,你在 Visual Studio 11 裡去點擊 InstallShield 專案,它還是帶你到 InstallShield for Visual Studio 2010 的下載安裝頁面。Visual Studio 11 未來正式版在【安裝與部署】會如何,我們無法得知,不過,Visual Studio 本身預設的安裝專案不見了,還是讓人擔心。

這時,遠方有個聲音傳來說:「不用怕!Advanced Installer 出現了。」

ASP.NET Web API 心得筆記 (2) REST 入門簡介

我接下去還會有幾篇關於 ASP.NET Web API 的文章,但看完黑暗執行緒的「RESTful探索系列」才發現,如果沒有先了解 RESTful,那接下去的內容還真有點硬,像是專業名詞,例如,你在 ASP.NET Web API 文件中可以看到大量的 Resource (資源) 這個單字,URI 我還能理解,跟 Resource 有什麼關係?

以下主要對 REST 做入門簡介,理解整個 REST 能讓我們在 ASP.NET Web API 的路上更順暢。

何謂REST

REST ( REpresentational State Transfer ),State Transfer 為 "狀態傳輸" 或 "状态转移 ",Representational 中文有人翻譯為"表徵"、"具象",合起來就是 "表徵狀態傳輸" 或 "具象狀態傳輸" 或 "表述性状态转移",不過,一般文章或技術文件都比較不會使用翻譯後的中文來撰寫,而是直接引用 REST 或 RESTful 來代表,因為 REST 一整個觀念,想要只用六個中文字來完整表達真有難度。
在我的《朗文當代辭典》中是這樣解釋 Representational:「a representational painting or style of art shows things as they actually appear in real life」(具體的繪畫或藝術風格所顯示的東西,實際出現在真實生活中)
REST 一詞的出於《Architectural Styles and
the Design of Network-based Software Architectures》論文,我們先簡單從標題來看,它應該是一種架構樣式 (Architectural Styles) 與軟體架構 (Software Architectures),而且是以網路 (Network-based) 為基礎,重點就是:

  • 架構樣式 (Architectural Styles)
  • 軟體架構 (Software Architectures)
  • 網路 (Network-based) 為基礎

REST 本身是設計風格而不是標準。REST 談論一件非常重要的事,如何正確地使用 Web標準,例如,HTTP 和 URI。想要了解 REST 最好的方式就是思索與了解 Web 及其工作方式。如果你設計的應用程式能符合 REST 原則 (REST principles),這些符合 REST 原則的 REST 服務可稱為 "RESTful web service" 也稱 "RESTful Web API"。"-ful" 字尾強調它們的設計完全符合 REST 論文裡的建議內容。

金剛帶小孩 - 參與,才會有感情

我很 enjoy 在家庭生活中,我與婆婆每天都有一些單獨相處時間,我與孩子們也一樣,每天都有一些只有我與孩子單獨相處的時間。雖然只是短短數小時,雖心有不甘,但我學習放下。

為什麼心有不甘?

婆婆因工作關係,上下班時間與一般人不一樣,所以晚上下班後,我是全職保母,剛開始真是有點不習慣。以前,回家帶小花散步後,就是回到電腦前面,但現在,除非有重要的事,不然晚上很少能打開電腦。剛開始時,每次都是一邊照顧她們,一邊心想,等一下等她們睡著後,我要做什麼什麼事。後來發現,這樣的不專心,照顧的效果非常差。

沒有心,和我們寫的程式《有魂無體(參考 topcat 文章)》一樣糟糕。後來想想,能與孩子好好的相處,不是自己一直想做的事嗎!真的給你機會,又心不在焉的一直想回到電腦的身邊。我慢慢學習,下了班,就把公司、電腦、技術…放在公司就好

最近,很少有空能寫寫我與她們的事,原因很簡單,搞定她們,我也累了。當我選擇下班後,把全心都給她們後,我發現,我們與她們的感情每天都在加深加厚。這讓我們想通了一件很簡單的道理,只要是「情」字,親情、感情、愛情、友情…你都必須用心參與才會產生連結(Connection),進而產生越來越深的關係。