如何撰寫 API 所需具備的知識

共计 4665 个字符，预计需要花费 12 分钟才能阅读完成。

本篇多數直接引入  淺談 REST 軟體架構風格 (Part.I) – 從了解 REST 到設計 RESTful！

1. REST Constraints – REST 條件 / 原則

REST 在概念上提出了幾項 Constraints (條件 / 原則)，當我們的設計系統符合這些 Constraints 的時候，我們可稱這個系統為 RESTful。REST 提及的 Constraints 如下述 六點：

• • 客戶 - 伺服器（Client-Server） – 使用主從式架構設計。
  • 無狀態（Stateless） – Client 與 Server 的溝通不需依賴狀態，每一個 Request 必須包含所有需要的資訊，而不需依賴其他 Request 的狀態。如此便能夠，目的是為了改善 Visibility (可視度), Reliability (可靠性，容易從錯誤中復原，維持正常的運作), Scalability (可擴展性，輕易地將 Request 交給其他 Server 進行處理) 能力。
  • 緩存（Cache）– 可實作快取，且快取機制可以在 Client 或 Server 中實作。
  • 統一接口（Uniform Interface） – 在 Components (後面會介紹 REST Components) 之間使用一致性的操作介面，為了透過介面降低耦合並提高獨立性 (Independent)。其中 REST 對 Interface 定義了四種限制（目前我認為 Uniform Interface 就是 REST 的核心價值，有效的藉由抽象介面來隔離實作細節）：
    • Identification of resources : 唯一的資源識別方法 Resource Identifiers (Nouns)，在 HTTP 即是 URL
    • Manipulation of resources through representations : 透過特定的操作方法來操作資源 (verbs)，在 HTTP 即是 GET, POST, PUT ,DELETE Mothods
    • Self-descriptive messages : 自我描述資訊，在 HTTP 即是 Content-Type
    • Hypermedia as the engine of application state : (我不了解這想表達什麼!? 殘念 …….)
  • 分層系統（Layered System） – 可分層的系統架構，目的在於隱藏介面後的實作細節，使得系統更容易實現快取、加密等等機制。
  • 按需代碼（Code-On-Demand，可選） – 可執行程式碼的設計，像是 JavaScript（非必要實作項目）

2. REST Architectural Elements – REST 架構元素

REST 定義了三種角色，分別是 Data Elements, Connectors 與 Components。

2.1. REST Data Elements

• Resource – the intended conceptual target of a hypertext reference
• Resource identifier – URL, URN
• Representation – HTML document, JPEG image
• Representation metadata – media type, last-modified time
• Resource metadata – source link, alternates, vary
• Control data – if-modified-since, cache-control

一般來說 Distributed Hypermedia Architect (分散式超媒體架構) 通常有以下三個實作方式，也有各自的優缺點：

1. 傳送者將資料 Render 後傳送給接受者，如此的方式對於接收者來說實作最簡單。但是由於傳送者的 Render 功能限制，系統的 Scalability (可擴展性) 相當的差。（傳統的 Web MVC 實作常看見這樣的架構）
2. 封裝資料與 Render Engine 然後一起傳送給接收者。如此能夠有效的封裝資料，缺點為有可能造成過高的資料傳送成本。
3. 傳送原始資料 (RAW Data) 與 Metadata 给接收者，根據使用者可用的 Engine 自行 Render。優點為傳送資料的成本較低，缺點為對於資料的隱藏性較差，而雙方必須對 Data Type 有一定的共識。

REST 混合了這三種實作方法，但 REST 最主要的貢獻在於明確地抽離 Client 與 Server 的耦合性，透過一致性的介面進行溝通，大幅增加 Server 的 Scalability (可擴展性)。

Resources and Resource Identifiers (資源識別子) – Data Elements 主要的概念為 Resources，在 REST 的系統架構中所有的 Entity (實體) 使用全域唯一的 Resource Identifiers 進行識別與定義（全域的目的為盡可能讓這樣的識別資源方法在不同系統中能夠正確地指向唯一的實體），並且有效地將實體資源與 Resource Identifiers 進行 mapping。資源存取者透過 Connectors 操作資源，然而很重要的一件事，這樣資源的識別命名方式能夠直覺與合理是最好不過的。

Representations – 在 REST 的概念中 Components 之前是透過 Representations 來表示這個資源目前的狀態，Representations 就像我們所熟悉的 Content-Type。假設我們取得某個人在某個網站當前的照片，image/jpg 這樣的 Content-Type 就是一種 Representations; 當然我們也可以取得這個人在這個網站當前的個人基本資料，或許 Content-Type 會使用 application/xml (又是另一種 Representations)。Client (User Agent) 在實作上會依據 Representations (就是 Content-Type) 來正確地 Render 訊息，這樣的行為是不是很像我們在使用的瀏覽器呢？

2.2. REST Connectors

REST Connectors 包含了以下五種型態：

• Client – libwww, libwww-perl
• Server – libwww, Apache API, NSAPI
• Cache – browser cache, Akamai cache network
• Resolver – bind (DNS lookup library)
• Tunnel – SOCKS, SSL after HTTP CONNECT

這些 Connectors 透過抽象的介面與 Components 進行溝通，在 REST 中所使用的連線都必須是 Stateless (無狀態)。Connectors 主要的形態為 Client 與 Server，由 Server 監聽 Client 所發出的 Request 並且回應 Response（連線機制與 HTTP 完全相符）。然而 Cache 的機制可以實作在 Client 或 Server 中（像是 Browser 與 Server 的 Cache 機制）；Resolver 能夠在 Client 與 Server 的溝通上正確的進行解析處理；Tunnel 可以強制進行加密等等的工作。有趣的是這些功能都是獨立的，對於操作者來說都是隱藏且不可見的。

2.3. REST Components

REST Components 包含以下四種角色

• User Agent – Netscape Navigator, Lynx, MOMspider
• Origin Server – Apache httpd, Microsoft IIS
• Gateway – Squid, CGI, Reverse Proxy
• Proxy – CERN Proxy, Netscape Proxy, Gauntlet

User Agent 使用 Client Connector 對 Server 進行連線（User Agent 就像是瀏覽器），並且實作如何正確地 Render 來至於 Server 的 Response。Origin Server 透過 Server Connector 並且提供一個通用的 Interface 來接收 Request，透過 Interface 隱藏 Resource 的實作細節。就像我們使用 Browser 瀏覽網站的時候，不需要知道網站是用什麼樣的技術實現的。而 Gateway 與 Proxy 能夠在 Client 與 Server 溝通的過程中增加效率與安全性。

起初在看這些概念是一頭霧水，等到實做過後才發現，這六點概念的核心價值，對於分層架構的理解，不僅是傳統的 MVC 還有延伸的資料處理層、業務處理層、頁面表現層，大概是這樣的概念。

額外延伸閱讀

什麼是 REST 跟 RESTful?

Representational State Transfer (REST)

WhatIsREST