API集成檢查表

0）快速瀏覽（誰在做什麼）

• 集成所有者已指定
• 電話聯系（24 × 7/奴隸。時鐘）拼出
• 同意的SLO/SLA和發行支持窗口
• 狀態頁面和事件渠道（電子郵件/Slack/Webhook）

1）可用性,環境,版本

• 已訪問sandbox/staging/production
• API版本確認：「/v1」/標題 「X-API-Version」
• Allowlist IP和網絡規則配置
• 時鐘和TZ：在UTC, NTP同步
• 通過SemVer和版本矩陣驗證了SDK/客戶端兼容性

2）身份驗證和令牌

• 該機制是一致的：OAuth2 Client Credentials/Auth Code+PKCE/API Key/mTLS
• Access Token生命周期和Refresh Token輪換設置
• 對於API Key：秘密顯示一次,保存在秘密管理器
• JWKS/JTI/'kid'已檢查,包括時鐘skew ± 5分鐘
• 「授權」標題不合理（修訂版）

bash curl -sS -H "Authorization: Bearer $TOKEN" https://api. example. com/v1/ping

3）安全和隱私

[] TLS 1.2 +/HSTS，可選mTLS

• PII最小化：我們只發送正確的口罩
• 保留和處置政策（GDPR/DSAR）已記錄
• Secret rotation：主動/下一鍵,滾動計劃
• 防盜：kapcha/密鑰創建速度/註冊限制

4）限制，配額和後綴

• 宣布「X-RateLimit-」/「X-Cota-」標題
• 客戶尊重429和「Retry-After」
• Retrai僅適用於5xx/408/429，指數backoff+jitter
• 設定試驗/時間限制（例如，≤ 5次試驗，≤ 60 c累計）

5）相似性和沖突

• 所有寫作操作均隨「Idempotency-Key」一起發送（TTL ≥ 24-72小時）
• 重復→沖突409 IDEMP_REPLAY正在處理
• ETag/'If-Match"用於競爭性更新的功能已啟用（如果可用）

bash curl -X POST /v1/payments \
-H "Idempotency-Key: pay-<uuid>" \
-d '{"amount":"12. 34","currency":"EUR"}'

6）分割和增量三角洲

• 使用cursor/keyset分區（「next_cursor」，「has_more」）
• 穩定排序'（updated_at、id）'已記錄
• 增量卸載：watermark或change token
• 重叠窗口（overlap 1-2 min）和dedup by '（id, version/seq）'

7）錯誤格式和診斷

• 單一格式「application/problem+json」 （RFC 7807）
• 字段支持：'error_code'、'trace_id'、'retriable'、'detail'
• 描述了錯誤映射和客戶端操作（runbook）

json
{
"type":"https://docs. example. com/errors/validation_failed",
"title":"Validation failed",
"status":422,
"error_code":"VAL_001",
"trace_id":"a1b2c3",
"retriable":false
}

8）Webhooks： 握手和重播

• 確認成功-任何2 xx；enqueue後快速ACK

[] Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`

• 撤退政策：backoff+Jitter，最長24-72小時
• DLQ+Replay：可用和驗證
• Dedup Storage在接收器、TTL ≥中繼窗口

9）可觀察性和跟蹤性

• 包括客戶端/SDK中的OpenTelemetry hooks
• 整個鏈條上的「trace_id」/「X-Request-ID」相關性

[] Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`

• 警報：5xx/429激增，p95上升，成功率下降，webhook脫落

promql rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

10）生產力和可持續性

• 連接池,保持活力,在可能的情況下HTTP/2/3
• 並發是有限的（後壓）,客戶的隊列不是「膨脹」
• circuit-breaker/timeout/fallback策略設置
• 負載測試：爆發10 ×，長連接，冷啟動

11）數據,貨幣,時間

• 格式：ISO-8601 UTC,金錢-十進制字符串/小單位,本地獨立於環境
• 編碼/語言是一致的（例如，消息的「接受語言」，但機器的「error_code」）
• 四舍五入政策/傭金記錄在案

12）核對和報告（重新計算）

• 與基準金額的每日/每小時核對
• 焊接的API/卸載已測試（CSV/JSON，清單/散列）
• 差異-在帶有「trace_id」鏈接的字幕中'

13）合規和法律方面

• 已接受API使用條款（公平使用/出口控制）
• PII/數據持有者-定義了角色和存儲區域
• 在事件中包括法律保留/審核操作日誌

14）文檔和開發門戶

• OpenAPI/AsyncAPI是最新的，「復制粘貼」示例是
• SDK （TS/Py/Java/Go/.NET）-版本一致,Cookbook可用
• Try-it playground工作正常,沙鍵處於活動狀態
• 在門戶網站上可以看到Changelog/解密/路由圖

15）測試： 功能,負面,混亂

功能性

• CRUD/關鍵腳本已通過（快樂路徑）
• 分離/遊標/增量增量

負面

• 401/403/404/409/422/429/5xx和「Retry-After」處理'
• 錯誤的webhook簽名，過期令牌，大身體

混亂

• Drop 10-30%的事件,reorder,延遲1-10分鐘
• 依存關系禁用（PSP/KYC） →正確的後退/錯誤

16）接收和啟動（直播）

• 最終的PRR（制作就緒評論）通過
• 金絲雀包容：10% → 25% → 50% → 100%
• 通過SLO信號自動回滾（錯誤/潛在性/429）
• 事件聯系矩陣和升級路徑已發布
• 飛行員後的CAPA backlog形成

17）運營和支持

• 運行手冊/花花公子：「5xx spike」，「429 storm」，「webhook backlog」，「timeout」
• SLO/Error Budget的定期報告
• 按計劃輪換機密和鑰匙
• 版本刪除/遷移計劃已商定（日落日期）

18）工件模板

env-config模板

yaml api:
base_url: https://api. example. com/v1 timeout_ms: 10000 retries: { max: 5, strategy: expo-jitter }
auth:
kind: oauth2 token_url: https://auth. example. com/oauth2/token scopes: [wallet:read, wallet:write]
webhooks:
secret_ref: secret/webhook-hmac parallelism: 10 max_body_kb: 256

Retrae Policy（偽）

json
{"initial":1,"max":60,"factor":2. 0,"jitter":0. 2,"retriable":["5xx","408","429"]}

19）最終簽名支票清單"

• 已準備好環境/版本/密鑰/allowlist
• Auth/JWT/keys/mTLS配置和測試
• 已實現限額/配額/恢復率/平均水平
• 分離/遊標/增量在數據上運行
• Webhooks：簽名、重播、DLQ/Replay驗證
• 「problem+json」、「trace_id」錯誤粘貼到所有日誌中
• Dashbords/Alertes組裝，OTel包括
• 通過負載/陰性/混沌測試
• 核對和報告收斂,runbooks正式化
• PRR/金絲雀/滾回計劃準備就緒，電話聯系人列出

底線

此表單關閉了API集成的技術、操作和合規方面。通過自上而下的項目，自動檢查極限，等效性和網絡圖書，包括可觀察性和回滾計劃-您的發布將可以預見，在生產中不會出現「驚喜」。