Enter your search text in the box above

Select a result to preview

API 設計決策框架 (API Design Framework)

#api-design #system-design #decision-framework

核心決策樹

設計 API 時，先問兩個問題：

                ┌───────────────────────────┐
                │  External client 或 Internal？ │
                └─────────┬─────────────────┘
                          │
          ┌───────────────┴───────────────┐
     External                          Internal
          │                                │
          ▼                                ▼
┌───────────────────┐                    RPC
│ Over/Under fetch  │                   (gRPC)
│ 是 concern 嗎？   │
└─────────┬─────────┘
          │
     ┌────┴────┐
     │         │
    Yes        No
     │         │
     ▼         ▼
  GraphQL    REST
兩個提問順序

  1. 對外還是對內？ → Internal 直接選 RPC
  2. Over-/Under-fetching 是痛點嗎？ → Yes 選 GraphQL；No 選 REST

三個選項的定位

範式 設計導向 對誰 預設場景
REST 資源導向（Resource） 對外 外部公開 API、跨平台、CDN 快取
GraphQL 查詢導向（Query） 對外 前端靈活查詢、避免 over-fetch
RPC 方法導向（Method） 對內 微服務高效能通訊

Over-fetching / Under-fetching 判斷

這是 REST 最常被質疑的兩個痛點：

現象 定義 例子
Over-fetching API 回傳比前端需要的多 只想要姓名，卻拿到整個 user object（含地址、生日、偏好）
Under-fetching 一個頁面需要多次 API call 才拿到所需資料 首頁要顯示：用戶 + 訂單清單 + 通知 → 3 次 call

什麼時候這會變成 concern？

Yes → GraphQL 有優勢

  • 行動裝置、弱網路 → 每個 byte 都重要
  • 複雜前端畫面（dashboard、feed）需要組合多資源
  • 前後端團隊分離，前端需求常變動

No → REST 就夠

  • 頻寬充足、畫面單純
  • 需要瀏覽器/CDN HTTP caching
  • 團隊熟悉度優先

為什麼 Internal 直接跳 RPC？

面試陷阱：過早跳到 gRPC

面試官想看你先解決功能性問題，再考慮協定優化。
正確順序：先 REST → 發現內部服務間有效能瓶頸 → 再改 gRPC。
外部 API 千萬不要一開始就提 gRPC。

混合策略（業界常見）

     ┌─────────────┐
     │  Browser    │ ◄──── REST / GraphQL (JSON / HTTP)
     └──────┬──────┘
            │
     ┌──────▼──────┐
     │ API Gateway │
     └──────┬──────┘
            │ gRPC (Protobuf / HTTP/2)
    ┌───────┼───────┐
    ▼       ▼       ▼
 Service  Service  Service

外部 REST/GraphQL + 內部 gRPC 是最常見的架構。

決策檢查清單

面試回答「我選 X」之前，先過一遍：

Simplification-with-exceptions

這張圖是簡化版

真實決策還要考慮：

  • 即時推送需求 → SSE / WebSocket / GraphQL Subscription（不是這張圖的範圍）
  • 大檔上傳 / 串流 → REST 的 chunked upload / gRPC streaming
  • 合作夥伴 B2B API → 雖然「對外」但可能用 gRPC + mTLS（雙方都是服務）
  • 遺留系統 → SOAP、XML-RPC 仍存在，但面試中幾乎不會提