三種請求-回應 API 的差別，一句話：REST 以資源為中心、RPC 以動作為中心、GraphQL 讓客戶端自己挑欄位。都跑在 HTTP 上，選錯的代價要好幾年才還得完——API 一旦有人用，幾乎改不動。
🧠 Core Ideas
TIP
問三個問題就分得出來：你暴露的是資源（REST）、動作（RPC）、還是讓客戶端組查詢（GraphQL）？先想清楚，因為 API 上線後就是對外契約，改不動。
- REST：資源即 URL（
/users/U123），用 HTTP 動詞表達意圖（GET/POST/PUT/PATCH/DELETE），狀態碼表達結果。名詞不要動詞。 - RPC：端點就是「要執行的動作」（
/conversations.archive）。REST 關注資源，RPC 關注動作。gRPC、Thrift 是高效能的 RPC。 - GraphQL：單一端點、客戶端在查詢裡精確指定要哪些欄位，伺服器回傳完全對應的結構。
⚖️ Tradeoffs
REST — 資源導向，標準但囉唆
- 善用 HTTP 既有語意（動詞、狀態碼、快取），標準化、好維護、生態成熟。
- 資源關係用子資源表達：
/repos/:owner/:repo/issues/:number。 - 不是所有操作都能塞進 CRUD——非 CRUD 動作有三種收法：當成資源欄位（
"archived": true）、當成子資源（PUT …/lock）、或直接用動詞（/search/code?q=）。 - 痛點：payload 容易膨脹（序列化器越加越多欄位）、一個畫面常要多次往返。
RPC / gRPC — 動作導向，輕量高效
- 兩條規則：端點含動作名、唯讀用
GET其餘用POST。 - 適合「暴露很多細瑣動作」「有與資源無關的副作用」「資源模型複雜」的場景（如 Slack 的 archive/join/kick/rename）。
- gRPC 這類走二進位序列化 + 明確 IDL，效能好；但跨網路呼叫始終比行程內貴好幾個數量級，別把它當成本地方法一樣狂呼叫。
- 痛點：動作難被發現、標準化程度低。
GraphQL — 客戶端組查詢，省往返但後端變重
- 單一端點、無需多種動詞；一次巢狀查詢就能跨資源取回剛好需要的資料，對行動裝置特別有感。
- 加欄位不破壞既有查詢 → 免版本；強型別 + 自省（GraphiQL）開發體驗好。
- 代價轉移到後端：伺服器要解析任意複雜查詢，效能難優化（第三方的使用模式無法預測）。
三者一覽
| REST | RPC / gRPC | GraphQL | |
|---|---|---|---|
| 中心 | 資源 | 動作 | 查詢語言 |
| HTTP 動詞 | 全套 | GET / POST | GET / POST（單端點） |
| 甜蜜點 | CRUD | 大量細瑣動作 | 需要查詢彈性 |
| 主要痛點 | payload 大、多往返 | 難發現、標準少 | 查詢解析貴、後端難優化 |
沒有萬用解——同一產品常同時提供多種（Slack 就 RPC + WebSocket + WebHook 並存）。
🔑 Takeaways
- REST 資源、RPC 動作、GraphQL 欄位——先確定你要暴露的是哪一種，再選典範。
- REST 是 CRUD 的安全預設；動作很多用 RPC/gRPC；前端要省往返、少版本煩惱就 GraphQL。
- API 是改不動的對外契約：版本策略、payload 大小、往返次數開頭就要想清楚。
No notes yet — jot your takeaways or Q&A here.