名詞解釋

本文件常用名詞。

API gateway ：應用程式存取各項服務的統一入口，負責認證、限流、計費、審計等橫切功能。

API key ：資料平面的認證金鑰，以 ak_live_ 開頭，放在 X-API-Key header。系統只保存其雜湊值。

資料平面（data plane） ：應用程式呼叫的業務 API（如 /v1/*），以 API key 認證並計費。

控制平面（control plane） ：管理員用的後台，以帳號密碼登入，管理 key、credit 與方案。

Credit（點數） ：用量計費的單位。每把 key 有自己的餘額，成功呼叫時依端點權重扣點。

Cost weight（成本權重） ：各端點扣除的 credit 數量；管理／系統端點為 0。

Plan（方案） ：一組共用的限流（RPS／Burst）與 credit 規則，建立 key 時指定。

RPS ：每秒請求數（requests per second），限流的速率參數。

Burst（突發容量） ：短時間內可累積的請求容量，超出穩定速率時的緩衝。

回應信封（envelope） ：統一的回應外層結構——成功為 { data, meta }，錯誤為 { error }。

meta ：回應信封中的中繼資訊，可能含 request_id、pagination、credit_cost、credit_remaining。

Request ID ：每個請求的追蹤碼，見於 X-Request-Id header 與 meta.request_id，用於對帳與客服。

Webhook ：事件發生時，由本服務主動以 HTTP POST 推送到你登記的網址，並以 HMAC 簽章驗證來源。

Secret（webhook 密鑰） ：用來驗證 webhook 簽章的金鑰，建立訂閱時一次性回傳。