REST API 如何運作——一次請求的來回

在一張互動畫布上呈現 REST API 如何運作：組成 HTTP 請求、伺服器上的路由與驗證，以及令這趟來回完成的回應。

REST API 是一場以 HTTP 進行的對話：用戶端送出一個指名資源與動作的請求，伺服器處理它，而回應則承載狀態碼與結果。

REST API 如何運作——一次請求的來回

The interactive FlowJam canvas for this explanation — every lane, row and arrow above is a real QueryChart diagram you can open and edit.

How to read this visual

  • 由左至右讀這三條直欄：請求、伺服器處理、回應。
  • 用戶端那一列與伺服器那一列交替出現，因此每一個箭頭要麼是用戶端送出些甚麼，要麼是伺服器決定些甚麼。
  • 「請求是否有效？」這個決策會通往順利的路徑，或者通往那個拒絕終點——這就是每一次 API 呼叫都可能出現的兩種結果。

請求

「用戶端組成一個 HTTP 請求（方法、URL、標頭、主體）」是每一次 REST 互動的起點。方法就是動詞——GET 讀取、POST 建立、PUT 取代、PATCH 更新、DELETE 移除——而 URL 為資源命名，所以 /users/42 就是讀取某一位用戶的那個請求。「用戶端透過 HTTPS 送出請求」是傳輸：REST 跑在 HTTP 之上，而 HTTPS 在其他圖解所描繪的同一套互聯網基礎設施上，令這場對話保持私密。

伺服器的工作

「伺服器把 URL 路由到對應的處理程式」把請求對應到程式碼，而「請求是否有效？」就是那道關卡：身分驗證（你是誰）、授權（你是否獲准）與內容主體的驗證全部在此發生，失敗的會送去拒絕終點「伺服器傳回 400 / 401 / 403」。「處理程式執行業務邏輯」與「伺服器在資料庫中讀取或寫入該資源」才是真正的工作——那是用戶端永遠看不見的部分。

回應

「伺服器組成帶有狀態碼與 JSON 主體的回應」就是契約的機器形態：200 代表成功、201 代表已建立、404 代表找不到、500 代表伺服器故障。「用戶端收到回應並解析它」與「用戶端把結果呈現給用戶」令整個回路完成——這趟來回在它開始的地方結束，也就是用戶端，而這正是圖解要回到用戶端那一列的原因。

Key relationships and takeaways

  • REST 是一份以 HTTP 寫成的契約：方法是動詞，URL 是資源，而狀態碼是機器可讀的結果。
  • 用戶端是無狀態的——每一個請求都帶齊伺服器所需的一切，因此不需要共用的工作階段。
  • 驗證就是保安邊界；無效的請求會在任何業務邏輯執行之前被拒絕。
  • 一個回應先由它的狀態碼定義，其次才是它的主體。
  • REST 的流量跑在其他技術圖解所描繪的同一套 DNS、HTTPS 與互聯網基礎設施之上。

When to use this visual

  • 在工程師設計第一個端點之前，向他們講解 HTTP 方法、URL 與狀態碼這個模型。
  • 按 REST 的慣例覆核一個 API 的契約——錯誤是用狀態碼表示，還是用 200 加一個旗標？
  • 把關於冪等性與快取的討論，落到請求實際是如何組成與驗證之上。

運作方式

  1. 把你自己的端點對應到請求方框上

    加入備註，列出你真實的方法與路由——GET /orders、POST /payments——令圖表記錄下你的 API 表面。

  2. 寫出你的狀態碼

    在回應那一步標註你的 API 針對每一種結果實際傳回的代碼，並加上你的契約中 200 與 400 以外會用到的那些。

  3. 加入身分驗證

    在用戶端與驗證關卡之間插入權杖那一步——Authorization 標頭中的一個 JWT 或 OAuth 權杖——以顯示身分是在哪裡進入請求的。

  4. 把重試與失敗的分支畫出來

    為網絡故障、速率限制與伺服器錯誤各自加上明確的終點，每一個都附上它所觸發的用戶端行為（重試、退避、錯誤狀態）。

常見問題

甚麼是 REST API？

REST API 是一組把系統的資源公開出來的 HTTP 端點。用戶端以 HTTP 方法對資源動作——GET 讀取、POST 建立、PUT 或 PATCH 更新、DELETE 移除——而伺服器以一個狀態碼和一份表示回應，通常是 JSON。REST 是一種風格而不是一項標準，它的價值在於任何懂得 HTTP 的用戶端都可以使用它。

GET、POST、PUT 與 DELETE 有甚麼分別？

它們是 REST 契約的動詞。GET 讀取一個資源，而且不應有副作用。POST 建立一個新資源並傳回它的識別。PUT 整份取代一個資源，而且是冪等的——重複執行不會再有任何改變。PATCH 做部分更新。DELETE 移除一個資源。動詞加上 URL 一起指明完整的動作，這就是為甚麼圖解中的請求方框首先點出方法。

狀態碼在 REST 裡為甚麼重要？

因為它們是請求的機器可讀結果。用戶端可以按狀態碼分支而不必解析主體：2xx 是成功、4xx 是用戶端的錯、5xx 是伺服器的錯。那些傳回 200 卻在主體裡放一個錯誤旗標的 API 破壞了這份契約，逼使每一個用戶端都要為那個回應寫特例。

怎樣才算是一個「RESTful」的 API？

實用的檢查清單：以 URL 為資源命名、以 HTTP 方法表達動作、無狀態的請求（每一個都帶齊伺服器所需的一切）、正確使用狀態碼的回應，以及常見的超媒體或版本化 URL。畫布模擬的正是那趟來回——請求、驗證、處理、回應——這就是每一次 RESTful 交換所共有的形狀。

用 QueryChart（FlowJam）編輯這張圖解

把上面這張 REST 畫布開啟為你自己的圖表——把用戶端與伺服器改名成你的服務，並為你的端點加上註解。

用 QueryChart（FlowJam）編輯這張圖解

互動圖解的更多內容