[筆記] ASP.NET MVC5 - Ch.13 Web API 2

Web Service

Web Service 架構出一種平台中立的網路服務，讓應用程式可以透過 URL 指向網際網路任何一台服務器所提供的服務

主要角色共有三種：提供者（provider）、消費者（consumer）、中介者（broker）

Provider 開發 Web Service
Provider 將 Web Service 部署至伺服器環境，並向 Broker 登入相關資訊至 UDDI 註冊資料庫
Consumer 到 UDDI 註冊資料庫搜尋所需的服務
Consumer 取得 Web Service 資訊後，開始使用該服務

關於 Web Service 架構，有三個重要的元素：

SOAP（傳遞訊息的格式）：SOAP（Simple Object Access Protocol）是架構在 HTTP 之上的物件存取協定，也就是說透過 HTTP 來傳遞訊息，而訊息的內容則是以 XML 格式來描述
WSDL（描述服務的內容）：WSDL（Web Services Description Language）是一份以 XML 撰寫的文件，副檔名就是 .WSDL，其主要的用途是「描述 Web Service」，也就是讓用戶端知道如何使用 Web Services
SOAP Discovery（又稱為 Disco）：開發人員將一個 Web Service 設計完成之後，可以將它登錄到一個集中的地方，其他人就可以向這個集中地查詢找到需要的服務。登錄與查詢的機制依賴 UDDI（Universal Description, Discovery and Integration）來達成

簡言之，XML + SOAP + WSDL + UDDI = Web Service 架構

ASP.NET Web API 2

Web API 的路由與 MVC 類似，在 WebApiConfig.cs 裡面設定路由規則：

public static class WebApiConfig
{
  public static void Register(HttpConfiguration config)
  {
    config.MapHttpAttributeRoutes();

    config.Routes.MapHttpRoute(
      name: "DefaultApi",
      routeTemplate: "api/{controller}/{id}",
      defaults: new { id = RouteParameter.Optional }
    );
  }
}

REST

REST 是 Representational State Transfer 的縮寫

資源（Resource）

分為 URI、URL、URN 幾種，其中，URI 包含 URL 及 URN：

uri-url-urn

URL 指示一個網際網路資源，並指定對其進行操作或取得該資源的方法。Web API 的 URL 不只代表 URL，它代表一個可被操作的資源，所以一般稱 Web API 的資源為 URI

URL：代表一個頁面的地址
URI：代表一個地址，以及提供的服務

URI

URI 分為三個部分：

服務位置（Service Address）：這個 Web API 的位置
資源（Resource）：提供哪些資源可進行操作
參數（Parameter）：與資源互動過程中，所需要的參數

HTTP 動詞

HTTP/1.1 協定中定義了 8 個 HTTP 動詞：OPTIONS、GET、HEAD、POST、PUT、DELETE、TRACE
HTTP 動詞用來向伺服器端說明，要對資源進行何種操作

GET

說明：用 GET 取得 URI 資源的具像（Instance）
請求：按 HTTP/1.1 規定，只有標頭，沒有本文（only request header, no request body）
回應：所請求 URI 資源的具像，通常帶有一個本文。回應標頭要與回應的具像一致（Same data type between response header and response）

POST

說明：使用 POST 讓資源在伺服器進行一系列的動作，例如建立新的資源
請求：一個資源的具像
回應：一個資源的具像，或是一個重新導向指令
POST、PUT、PATCH 與伺服器溝通的過程中，必須指定 Content-Type 標頭來與伺服器說明要使用的溝通格式，在 Web API 2 預設支援 XML 與 JSON：application/json 與 application/xml

PUT & PATCH

說明：PUT 動詞用來完整更新或替換一個現有的資源
請求：一個資源的具像
回應：更新的狀態
PATCH 動詞在 HTTP 規範中代表部分更新

DELETE

說明：使用 DELETE 動詞刪除資源
請求：只有標頭，沒有本文
回應：成功或失敗的狀態

HTTP 動詞與 URI

以前面的 route template 為例：api/{controller}/{id}

如果請求為以下：

GET http://localhost:8733/api/products

路由會用 route template，會在 ProductsController 裡面搜尋符合的方法

假設 ProductsController 裡面有兩個符合的方法：

public IQueryable<Product> GetProducts() {...}
public IHttpActionResult GetProduct(int id) {...}

兩個都是 Get 開頭，但 Web API 2 會選擇執行 GetProducts，因為它更符合 URI 請求無參數的事實。但如果請求是 /api/products/5，則會執行 GetProduct 這個方法

總結

Web API 2 專注於提供 HTTP Service
支援 XML 格式器提供相容性
不想傳統 web service 需要多種協定（XML+SOAP+WSDL+UDDI），只需要 HTTP 協定
使用 JSON 作為預設傳輸格式，為更多 client 端所接受

Web Service#

ASP.NET Web API 2#

REST#

資源（Resource）#

URI#

HTTP 動詞#

GET#

POST#

PUT & PATCH#

DELETE#

HTTP 動詞與 URI#

總結#