觀察

REST 在論文中由六個約束從 null style 逐步推導：client-server、stateless、cache、uniform interface、layered system、code-on-demand（optional）。Uniform interface 是 REST 的區別性特徵、由四個子約束構成：resource identification、manipulation through representations、self-descriptive messages、hypermedia as the engine of application state。文中明示 uniform interface 以效率為代價換取一般性與互動可見性。

判讀

這是所有 REST 論爭的 SSoT 錨點 — 純粹派、pragmatic 派、hypermedia 復興派都引用它。教學價值在揭露「REST 是約束集合、不是 URL + JSON + 動詞的 checklist」、並建立「約束是有 trade-off 的推導結果、不是教條」的框架。

對應大綱

REST 語意學之爭（定義基準、已引用）、11.3 資源建模（representation 概念來源、已引用）。

下一步路由

回 模組十一案例庫。

引用源

• Architectural Styles and the Design of Network-based Software Architectures, Chapter 5（Roy Fielding、2000）

原義：REST 是約束推導的結果

Fielding 的博士論文第 5 章給出 REST 的原始定義方式：從 null style 出發、逐一施加六個架構約束 — client-server、stateless、cache、uniform interface、layered system、code-on-demand（optional）— REST 是這組約束共同推導出的架構風格（見 11.C1）。

原義有兩個常被略過的重點。第一、uniform interface 是 REST 跟其他網路架構風格的區別性特徵、它自身再由四個子約束構成：resource identification、manipulation through representations、self-descriptive messages、hypermedia as the engine of application state — HATEOAS 在原義裡是定義的一部分、而非進階選配。第二、論文明文陳述 trade-off：uniform interface 以效率為代價、換取一般性與互動可見性 — 原義自己就把 REST 定位成有成本的選擇、而非普遍最優。

劃線：定義者的公開否定

2008 年、Fielding 在 blog 上對自稱 REST 的 RPC-style API 公開劃線、列出六條規則：協定獨立、不改標準協定、描述精力放在 media type 與 relation name（而非逐 URI 逐方法的文件）、server 擁有自己的 namespace（client 不得假設固定 URI 結構）、resource type 對 client 不可見、所有 application state transition 由 client 從 server 提供的選項中選擇驅動（見 11.C2）。

這篇文章給了爭論一條可操作的判別線：client 需要 out-of-band 文件才能操作的 API、就通不過 Fielding 意義的 REST — 依這條線、絕大多數自稱 RESTful 的 JSON API 都在線的另一側。同一位作者在 2014 年的 InfoQ 訪談把這條立場推進到版本策略：hypermedia 驅動的 API 用執行期演化取代版本號（該立場的展開見 版本策略章 與 11.C14）。

業界慣行的自我辯護

業界這一側的論證同樣完整、代表性的立場文逐條拆解 hypermedia 的收益假設：client 開發者實務上讀文件直打 endpoint、不會跟連結走（解耦收益落空）；hypermedia 格式無共識、「不會出現資料版的瀏覽器這種 generic REST client」；hypermedia 傳遞不了資料語意、文件仍不可免；複雜度與 response 膨脹沒有換到等比收益（見 11.C8、對照組）。結論是保留 stateless 資源設計的收益、捨 HATEOAS — Twitter、Facebook 等大型 API 被引為這條 pragmatic 路線的成功例。

這篇的論證方式是整場爭論的關鍵分野：它把爭點放在收益而非定義 — 主張定義裡有一塊在自己的場景不划算、名詞本身未被攻擊（C8 判讀）。這讓兩方的分歧從「誰對」變成「收益前提在誰的場景成立」— 收益假設的逐條交鋒、主寫在 Hypermedia 與 HATEOAS 復興。

第三方史觀：挪用、但自成合理架構

第三方的歷史考據給了這場爭論一個雙方都不冤枉的定調（見 11.C9、二手來源）：論文寫於 2000 年、談的是 HTTP/1.1 的設計理據、當時「web API」尚不存在；業界在棄 SOAP 時需要一面學術大旗、把 pragmatic 的 HTTP 用法掛上了 REST 的名字；Rails 2007 移除 SOAP 支援是這場轉向的符號性節點。史觀的結論止於此：名字確實被挪用、但挪用後的做法自成合理架構。把這個定調再推一步是本文的判讀：這套慣行 — 資源化 URL、正確的 method 與 status 語意、JSON 表徵 — 缺的只是一個不與原義衝突的名字。

這場爭論對工程溝通的用處

定義權之爭本身沒有工程結論、但它對日常溝通有三個直接可用的產出。第一、跨團隊溝通時把詞說死：「REST」在 API design review 裡是歧義詞、規範文件（11.10 治理 的 guidelines）該明文定義自家用法 — 多數組織的誠實寫法是「HTTP+JSON、資源導向、Richardson Level 2」、而非裸的 RESTful。第二、判別線當設計問句用：「這個 client 需要多少 out-of-band 知識」是好問題、無論最終給出哪一側的答案。第三、引用要對版本：引 Fielding 支持自己的 URL 命名慣例、引到的多半是業界慣行而非原義 — 這類錯位引用在 style guide 裡很常見、寫規範時值得回一手來源核對。

下一步路由

• 復興派的完整論證與反方交鋒：Hypermedia 與 HATEOAS 復興
• 分級定位工具：Richardson 成熟度的實用讀法
• 中性判準層：11.3 資源建模與操作語意
• 案例原文：模組十一案例庫

觀察

Fielding 在 2008 年的 blog 文列出六條 REST API 規則：協定獨立、不改標準協定、描述精力放在 media type 與 relation name（而非逐 URI 逐方法的文件）、server 必須擁有自己的 namespace（client 不得假設固定 URI 結構）、resource type 對 client 不可見、所有 application state transition 必須由 client 從 server 提供的選項中選擇驅動。文中直接批評自稱 REST 的 RPC-style API 造成過度耦合。

判讀

教學判準：「client 是否需要 out-of-band 文件才能操作 — 需要、就不是 Fielding 意義的 REST」。同時揭露命名權之爭：術語定義者與業界慣行的張力、是流派層敘事的起點。

對應大綱

REST 語意學之爭（核心案例、已引用）。

下一步路由

回 模組十一案例庫。

引用源

• REST APIs must be hypertext-driven（Roy Fielding blog、2008）

語意漂移史：復興派的問題意識

復興派的論證起點是一段歷史重建（見 11.C4）：XML-RPC 與 SOAP 世代之後、JSON 取代 XML 成為 API 的通用格式 — 但 JSON 是純資料格式、不是 hypertext、hypermedia controls 沒有了自然的載體；Richardson 成熟度模型普及、業界集體停在 Level 2；SPA 興起讓前端與 REST 原則脫鉤；GraphQL 最後乾脆放棄 REST 名義。重建的結論：今日的 JSON API 是掛著 REST 名字的 RPC、真正 hypermedia-driven 的回應形式是 HTML。

C4 的判讀從這段敘事抽出整場爭論的樞紐 — 一個兩派共享的觀察：REST 的 self-describing 特性是為 uniform client（瀏覽器）設計的、machine-to-machine 的 JSON 生態並不存在這種 client。復興派從這個觀察推出「所以回到 HTML、讓瀏覽器當 uniform client」；pragmatic 派從同一個觀察推出「所以 machine-to-machine 場景放棄 hypermedia」— 同一個前提、兩個方向的合理結論、分歧點在 consumer 是誰。

復興論證的正面版本

htmx 一系的 essays 把復興論證落到具體工程性質：業務狀態直接編碼在可用操作裡、client 端零業務邏輯（範例層見 11.C5 與 11.3 的展開）。從這個性質推下去（本文判讀）：狀態機改版時只有 server 要改、部署即生效、沒有 client 端的版本滯後 — hypermedia 於是成為 版本策略 的另一種解法：Fielding 的 no-versioning 立場（InfoQ 訪談、見 11.C14）在 hypermedia 前提下是自洽的 — 控制項在執行期習得、演化不需要版本號。

論證同時對 GraphQL 保留了讓步：thick-client 場景（client 本來就要持有大量邏輯）用 GraphQL 是合理選擇（此讓步出自 11.C4 的漂移史敘事）— 復興派的攻擊對象是「掛 REST 名的 JSON RPC」、而非所有非 hypermedia 的設計。

格式標準化的現實：JSON 上補 hypermedia 的失敗

復興論證有一個要正面回答的歷史事實：在 JSON 上疊 hypermedia controls 的嘗試、生態上失敗了。HAL 用 _links 與 _embedded 兩個保留屬性做最小侵入的 hypermedia 化、有 spec、有生態（曾是 Spring HATEOAS 預設格式）、標準化止步於過期的 IETF draft（見 11.C6）。Siren 走表達力路線、first-class 的 actions 帶 method 與欄位、比 HAL 更接近 HTML form 的 JSON 化 — 採用反而更少、release 停在 2017（見 11.C7）。

兩案並排的判讀：表達力不是 hypermedia 格式勝出的變數、client 生態才是 — HAL、Siren、JSON-LD、Collection+JSON 並立無一勝出、uniform client 沒有形成、每個消費者仍要為每個 API 寫專屬邏輯、hypermedia 的收益前提落空。這個碎片化現實同時支撐兩派：復興派引它證明「JSON 不是 natural hypermedia、所以回到 HTML」；pragmatic 派引它證明「別等標準收斂、直接放棄 controls」。

反方的收益假設拆解

Pragmatic 派的拆解針對的是收益假設而非名詞；本文把 C8 記錄的論據重組為三條假設逐一對應（重組是本文整理、原文論據見 11.C8、對照組）：解耦（decoupling）— client 開發者實務上讀文件直打 endpoint、不跟連結走；可發現性（discoverability）— hypermedia 格式無共識、「不會出現資料版的瀏覽器這種 generic REST client」；可演化性（evolvability）— hypermedia 傳遞不了資料語意、文件仍不可免。三條拆解共享同一個前提：消費者是程式、不是人 — 把這個前提換掉（消費者是瀏覽器後面的人）、三條拆解全部失效、這正是 htmx 一系在 web UI 場景成立的原因。

適用邊界

把兩派論證疊起來、hypermedia 的適用邊界可以畫得相當清楚。收益前提成立的場景：consumer 是瀏覽器（或任何會 render hypermedia 的 uniform client）、UI 由 server 驅動、業務狀態機常變 — server-rendered web 應用、後台管理介面、htmx 式的漸進增強前端。收益前提不成立的場景：machine-to-machine 整合、第三方開發者寫程式消費、mobile app 內建業務邏輯 — 這些場景的務實選擇是「狀態欄位 + 明文狀態機」路線（判準見 11.3）。誤區是把邊界問題當立場問題：同一個組織可以對外 API 走 pragmatic、後台 UI 走 hypermedia、兩者引用的是同一組論證的不同半邊。

下一步路由

• 這個詞的定義權爭奪全景：REST 語意學之爭
• 判別法與建模層判準：11.3 資源建模與操作語意
• no-versioning 立場的版本策略語境：11.5 版本策略與 deprecation
• 案例原文：模組十一案例庫

觀察

模型分四級：Level 0（HTTP 當 RPC 隧道、單一 endpoint）、Level 1（資源化、逐資源 URI）、Level 2（HTTP 動詞與狀態碼正確使用）、Level 3（hypermedia controls / HATEOAS）。Fowler 明文標注：RMM 是理解 REST 元素的思考工具、不是 REST 的分級定義；並記錄 Fielding 的立場 — 只有 Level 3 才算 REST。模型本身出自 Richardson 的 QCon 演講、此文屬權威轉述。

判讀

教學價值在雙重性：用 RMM 定位自己的 API 在哪一級是合法用法、拿 RMM 當 REST 認證是誤用。它也是「業界普遍停在 Level 2」這個實證現象的參照系。

對應大綱

Richardson 成熟度的實用讀法（骨幹、已引用）、11.3 資源建模（定位工具段、已引用）。

下一步路由

回 模組十一案例庫。

引用源

• Richardson Maturity Model（Martin Fowler、2010）

四級的工程意義

表格是索引、每級的躍遷各有實質收益。Level 0 到 1 的收益是結構：橫切能力（權限、審計、快取鍵）有了掛載單位。Level 1 到 2 的收益是讓基礎設施當盟友：GET 的安全承諾讓 proxy 敢快取、status 的語意讓監控與重試鏈正確運作 — method 與 status 作為承諾的完整判準在 11.3。Level 2 到 3 的收益是解耦 client 的業務知識 — 但這一級的收益前提（存在會跟連結走的 uniform client）在 machine-to-machine 場景多半不成立、完整交鋒見 Hypermedia 與 HATEOAS 復興。

兩個立場事實

用 RMM 之前要知道它在爭論光譜上的位置。其一、Fielding 的立場被 Fowler 記錄在案：只有 Level 3 才算 REST — 依原義、RMM 的前三級都是「還不是 REST」的程度差異、把 Level 2 說成「基本 REST」與原始定義者的立場直接牴觸（定義權爭奪的全景見 REST 語意學之爭）。其二、業界實務多停在 Level 2 — 這是廣泛的觀察、C3 案例的判讀層也如此標注、Fowler 原文沒有這個統計主張、引用時分清楚。

誤用一：當合規檢查表

「我們的 API 要通過 Level 2 審查」這類用法把定位尺變成認證考卷、產生兩種浪費。輕的浪費是形式主義：為了「正確使用 PATCH」而在沒有部分更新需求的資源上硬加 PATCH、級別達標、介面多了沒人用的表面積。重的浪費是誤導優先序：Level 2 的實質收益是中介層能讀懂介面 — 檢查的對象該是「快取有沒有實際命中、重試鏈行為是否正確」、而非 method 使用的字面合規。合規檢查表要從自家的 breaking 清單與錯誤模型長出來（11.6、11.4）、RMM 的粒度撐不起這個角色。

誤用二：當升級路線圖

「今年 Level 2、明年 Level 3」把分級讀成演進方向、隱含「越高越好」— 但 Level 3 的收益前提跟前兩級不同質：前兩級的收益（結構、基礎設施相容）幾乎無條件成立、Level 3 的收益依賴 uniform client 的存在。machine-to-machine API 升到 Level 3、成本照付（回應膨脹、格式選型、server 端組裝 controls）、收益不兌現 — 停在 Level 2 對多數 API 是刻意且正確的終點、而非未完成狀態。

實用讀法

RMM 最好的用法是三種對話場景。定位：「我們的公開 API 在 Level 2、後台 HTML 介面實質上是 Level 3」— 一句話讓新成員理解兩套介面的設計差異。驗傷：接手遺留系統時、「這批 endpoint 在 Level 0（全部 POST 打一個 /api）」直接指出重構的第一刀在資源化、而非欄位微調。止損：design review 有人提議「往 Level 3 走」時、RMM 的級別語言讓討論快速聚焦到真正的問題 —「我們的 consumer 是誰、誰會跟連結走」— 而非在抽象的成熟度上表態。三種用法的共同點：RMM 出現在句子裡是為了描述現狀與差異、而非評分。

下一步路由

• Level 2 的承諾語意展開：11.3 資源建模與操作語意
• Level 3 的收益前提交鋒：Hypermedia 與 HATEOAS 復興
• 定義權爭奪全景：REST 語意學之爭
• 案例原文：模組十一案例庫

觀察

Gross 重建語意漂移路徑：XML-RPC / SOAP 時代、JSON 取代 XML（但 JSON 是純資料、不是 hypertext）、RMM 普及但業界停在 Level 2、SPA 讓前端與 REST 原則脫鉤、GraphQL 乾脆放棄 REST 名義。結論：今日的 JSON API 是掛 REST 名的 RPC；真正 RESTful 的是 hypermedia-driven 的 HTML 回應。文中同時承認 GraphQL 對 thick-client 場景是合理選擇。

判讀

關鍵教學判準：「REST 的 self-describing 特性是為 uniform client（瀏覽器）設計、machine-to-machine 的 JSON client 用不上」— 這條是復興派與 pragmatic 派唯一共識的觀察、兩派從它推出相反結論、適合當章節的對照樞紐。

對應大綱

Hypermedia 與 HATEOAS 復興（主案例、已引用）。

下一步路由

回 模組十一案例庫。

引用源

• How Did REST Come To Mean The Opposite of REST?（htmx essays、Carson Gross）

觀察

essay 用銀行帳戶透支做對照：HTML 回應在透支時只回 deposit 連結 — 業務狀態直接編碼在可用操作裡、client 零業務知識；JSON 回應回 status: "overdrawn" 欄位、client 必須靠 out-of-band 文件理解語意與下一步 URL。結論主張 HTML 這類 natural hypermedia 是實作 RESTful 系統的 practical necessity、在 JSON 上疊 hypermedia controls 的做法已被業界廣泛拒絕。

判讀

教學判準：「available actions 由誰計算 — server 算完放進 response、還是 client 讀狀態欄位自己算」是 HATEOAS 有無的操作型判別法、比背定義有效。

對應大綱

11.3 資源建模與操作語意（範例主寫、已引用）、Hypermedia 與 HATEOAS 復興（範例層引用）。

下一步路由

回 模組十一案例庫。

引用源

• HATEOAS（htmx essays）

觀察

HAL 用 _links 與 _embedded 兩個保留屬性在 JSON 上表達 hypermedia controls、目標是讓通用函式庫可以在任何 HAL API 上重用（uniform interface）。狀態：IETF Internet-Draft（最新 v11）、已過期歸檔、無標準地位；生態面曾是 Spring HATEOAS 的預設格式。

判讀

教學判準：「格式碎片化（HAL / Siren / JSON-LD / Collection+JSON 並立、無一勝出）是 hypermedia JSON 未形成 uniform client 的結構性原因」— 這正是 Fielding 說要把力氣花在 media type 上、而業界沒收斂的實證。

對應大綱

Hypermedia 與 HATEOAS 復興（格式現實段、與 Siren 並列、已引用）。

下一步路由

回 模組十一案例庫。

引用源

• JSON Hypertext Application Language（IETF draft-kelly-json-hal、已過期）

觀察

Siren 用 entities / actions / links 三元件表達資源、特點是 first-class 的 actions（含 method 與欄位、比 HAL 的純連結更接近 HTML form）。採用現狀：約 1.3k stars、最後 release v0.6.2 停在 2017-04、media type application/vnd.siren+json。

判讀

教學判準：「表達力不是 hypermedia 格式勝出的變數、client 生態才是」— Siren 表達力上更完整（actions 近似 HTML form 的 JSON 化）、採用反而更少。同時支撐 htmx 派「JSON 不是 natural hypermedia」與 pragmatic 派「別等標準收斂」兩邊的決策。

對應大綱

Hypermedia 與 HATEOAS 復興（格式現實段、與 HAL 並列、已引用）。

下一步路由

回 模組十一案例庫。

引用源

• Siren: a hypermedia specification（Kevin Swiber、GitHub repo）

觀察

文章列四條反對論據：client 開發者實務上讀文件直打 endpoint、不會跟連結走（解耦收益落空）；格式無共識、「不會出現資料版的瀏覽器這種 generic REST client」；hypermedia 傳不了資料語意、文件仍不可免；複雜度與 response 膨脹沒有換到等比收益。主張保留 stateless 資源設計的收益、捨 HATEOAS、引 Twitter / Facebook API 為 pragmatic 成功例。

判讀

論證方式是逐條拆 HATEOAS 的收益假設（decoupling、discoverability、evolvability）在 machine-to-machine 場景不成立、而非攻擊名詞。教學判準：「HATEOAS 的收益前提是存在會動態跟連結走的 client — 先問你的 client 是誰、再決定投不投 hypermedia」。與 C4 / C5 形成同觀察、反結論的完整對照。

對應大綱

REST 語意學之爭 與 Hypermedia 復興（pragmatic 派立場、皆已引用）。反例。

下一步路由

回 模組十一案例庫。

引用源

• Pragmatic REST APIs without hypermedia and HATEOAS（Ben Morris）

觀察

考據指出：Fielding 論文寫於 2000、談的是 HTTP/1.1 的設計理據而非 API 建構（當時 web API 尚不存在）；業界在棄 SOAP 時需要學術正當性、把 pragmatic HTTP 用法掛上 REST 名字；Rails 2007 移除 SOAP 支援是轉折符號。

判讀

史觀的教學價值是中立定調：兩派都沒有冤枉對方 — 名字確實被挪用、但挪用後的東西自成合理架構。適合當「REST 語意學之爭」章節收尾的第三方視角、避免章節被迫選邊。

對應大綱

REST 語意學之爭（收尾史觀段、已引用）。二手來源、標明性質後使用。

下一步路由

回 模組十一案例庫。

引用源

• Roy Fielding’s Misappropriated REST Dissertation（Two-Bit History、2020）