部署管理與 API 策略

API 先是一份承諾，才是一個 endpoint

對使用者來說，API 的價值不在後端跑哪個服務，而在這份 contract 是否穩定：怎麼驗證身分、可以做什麼、回應多久、失敗後能不能重試，以及介面何時會改。

設計前先回答五個問題：

1. Consumer 是公司內的 workload、合作夥伴，還是不特定第三方？
2. API 處理公開資料、個資，還是付款等高風險操作？
3. 預期的 sustained traffic、burst、payload 和 latency SLO 是多少？
4. Consumer 要自助註冊、查看用量或購買方案嗎？
5. 團隊願意管理 proxy runtime，還是只想使用全代管入口？

同樣是 REST API，內部服務呼叫與對外販售資料的需求差很多。不要先看到 API 就選產品，也不是每個內部服務前都需要一套 API management platform。

Contract-first 不是先寫一份 YAML 就結束

OpenAPI document 或 gRPC proto 應該跟程式碼一起進版控，成為 design review、mock、client generation 和 compatibility test 的共同依據。實作流程可以是：

1. 先定義 resource、method、schema、error model、pagination 和 idempotency semantics。
2. 由 API consumer、security 和 operation 團隊一起 review。
3. CI 檢查格式、breaking change、example 和實作是否一致。
4. 在 staging 跑 consumer contract test，再逐步放量。
5. 上線後觀察各版本流量、錯誤與 consumer adoption，才決定何時退場舊版。

POST /orders 若因 timeout 重試兩次，會建立一張還是兩張訂單？這類問題若沒有寫進 contract，gateway 再完整也救不了資料一致性。

三種服務怎麼選

Apigee：經營一個 API program

Apigee 適合高價值或大量 API，需要跨團隊治理、合作夥伴 onboarding 和完整 API product lifecycle 的情境。API proxy 可套用 authentication、quota、spike control、message validation 和 transformation 等 policy；API product 能把 operation 組合成不同方案，再提供給 developer app。Developer portal、analytics 和 monetization 讓團隊能把 API 當產品營運。

若 runtime 必須留在自有 Kubernetes 環境、其他 cloud 或特定網路邊界，可評估 Apigee hybrid；若希望 Google 管理 runtime，則使用全代管的 Apigee。Hybrid 並不等於零維運，團隊仍要負責 runtime cluster、capacity、upgrade 和 connectivity。

Monetization 也不是打開開關就完成收款。Rate plan、entitlement、帳務流程、稅務與 portal 體驗仍要一起設計，並確認所選方案與地區支援需要的功能。

API Gateway：全代管的 HTTP API 入口

API Gateway 以 OpenAPI 2.0 configuration 定義 route、backend 和 authentication，適合用全代管 gateway 封裝 Cloud Run、Cloud Run functions、App Engine 或其他 HTTP backend。它能整合 API key、JWT validation、logging、monitoring 和 consumer quota，不必自行維護 proxy runtime。

它的定位不是完整的 partner ecosystem。若需求包含進階 policy、developer portal、API product、跨環境 governance 或 monetization，應重新評估 Apigee。產品的 resource、request rate 和 payload 也有限制，上線前要用預估流量與最大 payload 對照當期 quota 文件，不要把平台 quota 誤當成你對單一客戶承諾的方案額度。

Cloud Endpoints：把 ESPv2 放在 workload 前

Cloud Endpoints 是分散式 API management system。ESPv2 是 Envoy-based proxy，支援 OpenAPI 2.0 與 gRPC，可用 sidecar 或 remote proxy 方式部署，並透過 Service Management／Service Control 提供 authentication、API key、quota 和 telemetry。

這個選項適合需要 gRPC，或希望 proxy 靠近 GKE、Compute Engine、Cloud Run 等 backend 的團隊。舊 ESP 仍供既有使用者使用，但新設計應優先評估 ESPv2。

內部 API 不一定需要 API gateway

純內部 service-to-service traffic 可能只需要 workload identity、IAM、load balancing、service discovery 和 service mesh。若沒有 external onboarding、API product 或集中 policy 需求，硬加一層 gateway 只會增加 latency、成本與故障點。

簡單比較：

這張表是起點，不是關鍵字配對答案。最後仍要比較 protocol、policy、topology、operation model、quota 與總成本。

Authentication、authorization 與 API key 要分開看

API key 通常識別呼叫的 application 或 consumer project，適合 metering 和 quota；它不是 user identity，也不該單獨保護高風險操作。常見設計是：

• 對使用者使用 OAuth 2.0／OIDC，驗證 issuer、audience、expiry 和 scope。
• 對 workload 使用 IAM、service account 或 workload identity，避免散發長效金鑰。
• 需要雙向身分驗證時評估 mTLS，但仍要做 operation-level authorization。
• Gateway 驗證通過後，backend 還是要判斷這個 principal 能否讀取該筆資料。
• Gateway 到 backend 也需要受保護的身分與 channel，不能只保護 internet-facing 那一段。

所有 token、API key 和敏感 payload 都要避免寫入 log。Security policy 還要測 bypass path：consumer 是否能繞過 gateway 直接打 backend？

Quota、rate limit 和 retry 是同一個流量問題

Quota 常限制一段時間內的總使用量；rate 或 spike control 則保護短時間 capacity。它們要依 consumer、operation 和 backend capacity 設計，並明確回傳可辨識的 error、retry guidance 與 correlation ID。

Retry 必須搭配 exponential backoff、jitter、上限和 idempotency。若 gateway timeout 是 30 秒、client timeout 是 5 秒，client 可能已重試多次，而舊 request 仍在 backend 執行。架構師要把 timeout budget 從 client、gateway、service 一路排到 downstream，不能各自使用預設值。

API 變更要以 consumer 行為判斷

新增 optional field 常常相容，但不是保證。Strict client 可能拒絕未知欄位；新增 enum value 也可能讓沒有 default branch 的 client crash。修改 error code、sorting、null semantics、authorization 或 rate limit，即使 schema 沒變，也可能是 breaking change。

可靠的演進流程包括：

• 用 compatibility tooling 和真實 consumer contract test 檢查變更。
• 優先用 additive change，必要時才建立新 major version。
• 同時維護 migration guide、sample、SDK 和 changelog。
• 先通知已知 consumer，再用 telemetry 確認舊版流量是否真的歸零。
• Deprecation window 依合約、consumer release cycle 和風險決定，不硬套固定月數。
• Sunset 後清理 route、credential、monitoring 和 backend code，避免永久雙軌。

部署 API 時，驗證的是 contract 與使用者影響

Cloud Deploy 可把 release 推進到 GKE 或 Cloud Run target，支援 canary、verification、hooks、automation 和 rollback 等流程。Multi-target 可以管理多個 target；custom target 則要自行實作 render／deploy 行為與操作責任，並非宣告後就能部署任何平台。

API rollout 至少要檢查：

1. Artifact 以 immutable digest 識別，OpenAPI／proto 與實作來自同一 release。
2. Pre-deploy 執行 schema、security 和 compatibility test。
3. Canary 同時觀察 error、latency、quota rejection 與特定 consumer cohort。
4. Post-deploy 跑 synthetic transaction，而不只看 container 是否 ready。
5. Rollback 前確認 database migration 與 event schema 是否仍向後相容。

Cloud Deploy automation 可以依 rollout 狀態推進 phase、promotion 或 repair，但任意業務指標不會憑空變成 release gate。若要用 SLO 決定 promotion，必須把 Monitoring query、verification job 和失敗條件明確接進流程。

情境練習：開放庫存 API 給合作夥伴

一家零售商要讓物流夥伴查詢庫存並預留商品。合作夥伴需要自助申請、各自 quota、使用分析，未來可能依方案計費。

可行的設計順序是：

1. 先定義 consumer 與 business contract：查詢可接受稍舊資料，預留操作則需要 idempotency key、較強 authorization 和 audit trail。
2. 因為需要 API product、partner onboarding、portal 與 monetization，選 Apigee，而不是只因 backend 在 Cloud Run 就選 API Gateway。
3. OAuth token 識別 partner workload；API product 與 app association 控制它能呼叫哪些 operation。API key 僅用於 app identification／metering，不取代 authorization。
4. Read API 與 reservation API 分開 quota 和 spike control，後者的上限以 inventory service 與 database 壓測結果為準。
5. Backend 只接受來自受信任 proxy path 的 request，並再次檢查 partner 是否可操作指定倉庫。
6. 新欄位先跑 partner contract test；canary 只放少量 partner traffic，觀察 business error 和 duplicate reservation。
7. 舊版退場前，用 analytics 找仍在使用的 partner，逐一完成 migration，而不是日期到了直接關閉。

本課檢查清單

• API 選型從 consumer、risk、protocol、policy 和 operating model 開始，不做關鍵字配對。
• Apigee 適合經營 API program；API Gateway 是全代管 HTTP gateway；Endpoints 提供可自行部署的 ESPv2 與 gRPC 支援。
• API key 識別 application，不等於 user／workload authentication，也不完成 authorization。
• Quota、rate limit、timeout、retry 和 idempotency 必須一起設計。
• Schema 看似 additive 仍可能破壞 strict client；用 contract test 和 adoption telemetry 驗證。
• Release ready 不代表 user journey 正常；部署後要執行 synthetic 與 SLO verification。
• Rollback 不能自動倒轉 database、message 或外部 side effect。

延伸閱讀

• Apigee API management
• API Gateway quotas
• Cloud Endpoints architecture
• Cloud Deploy overview

下一步

下一課會把 API 上線後產生的 metrics、logs、traces 和 user journey 串起來，建立能指引行動的 SLO 與告警。