通過API進行操作

（部分： 業務和管理）

1）任命和原則

API是生態系統的「運營層」：任何沒有通過合同自動化的東西都會變成手工操作和風險。

• 合同第一：首先是規範（OpenAPI/JSON Schema/AsyncAPI），然後是實現。
• 安全默認：最小跳躍,短TTL, mutual-TLS/簽名。
• 觀察：終端跟蹤和SLA度量。
• Idempotent：重播是安全的。
• Backwards兼容：沒有「破裂」變化的進化。
• 可聽性：經加密確認的事實（收據）。

2）合同和模型（參考）

用於同步查詢的OpenAPI；用於事件/webhook的AsyncAPI。
每個資源中的必填字段為「id」、「version」、「created_at」、「updated_at」、「tenant」、「region」、「trace_id」。

合同部分的示例

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3）認證,授權,漏洞

面向用戶/合作夥伴的OAuth2/OIDC；client-credentials/JWT для S2S.

Scopes/資源角色： 'payments。write`, `catalog.read`, `audit.export`.

ReBAC：「通過擁有」訪問（tenant/帳戶/sab帳戶）。
JIT秘密：短壽命令牌,綁定到設備/子網/區域。
用於關鍵操作（付款、密鑰）的Device posture&mTLS。

4）相似性和「正好有一天」

Idempotency-Key（標題）+TTL窗口上的'（密鑰、帳戶、路線）'。
發布事件的Outbox/CDC-保證交付。
Exactly-once-effects：副作用通過事務日誌固定；重復產生相同的「收據」（「receipt_hash」）。
Retry Policy：指數後退、擠壓、最大窗口。

5）限制，配額，優先級

Rate limits: per-key/tenant/route/region;「軟」（429）和「硬」（截止）。
配額/預算：每月/每日配額，webhooks 「CotaCapReached」。
公平使用：服務級別的tenant優先級（黃金/銀/青銅）。
爆破緩沖區：短暫的爆發，沒有鄰居降級。

6）分離，過濾器，樣本

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.

雜誌/交易的抽樣時間（「from」，「to」，「watermark」）。

Filtering DSL: whitelisted поля, `?status=...&tenant=...®ion=...`.

Consistency hints： 「snapshot_at'/'as_of」用於報告API。

7）轉化與兼容性

SemVer: `v1`, `v1.1'（擴展），'v2' 僅通過新路徑/nijspace。
進化規則：僅通過窗口添加「deprecate → remove」字段/值。
兼容性測試：「合同即測試」（消費者駕駛）。

8）事件，網絡手冊和收據

AsyncAPI 描述主題/payload/簽名。
標題：HMAC/EdDSA，標題「X-Signature」，「X-Nonce」，「X-Timestamp」（窄窗口）。
收據（receipts）： 「receipt_hash」和DSSE簽名在關鍵事件（付款、RTP/限制更改、價格表）上。
Retrai和dedup：通過「idempotency_key」/「event_id」的冪等。
DLQ/檢疫：有原因的非驗證/重復消息。

9）可觀察性和質量

Traces： 通過網關/業務事件/webhooks強制性的「trace_id/span_id」。
Metrics：可用性,p50/p95/p99, error-rate, retry-rate, cost per 1k。
Logs：結構化，無秘密/PII；「tenant/region/version」標簽。
SLO/Alerts：面向SLO的條件和自動符文（pause/re-route/rollback）。

10）狀態的錯誤和語義

2 xx-成功（異步操作202個）。
4xx-客戶的過錯（422-驗證，409-沖突/平均值，429-限制）。
5xx-時間問題。
錯誤主體：「code」，「message」，「trace_id」，「hint」，「retry_after？」。
合作夥伴的UX：每個錯誤的「該怎麼做」表。

11）策略作為代碼（OPA/ABAC）

集中授權：「誰/什麼/何時/為什麼」。

Git、Code review、CI測試（飛行前： "政策會允許嗎？»).

SoD支票：「創建付款」≠「批準」。

12）安全、隱私、合規性

PII最小化：令牌/口罩，僅通過批準的喬巴訪問初級。
秘密：Vault/KMS，TTL短，輪換；禁止共享秘密。
加密：mTLS/TLS 1。3、AES-GCM at rest, HSTS/PKP在適當時。
Jurisdiction-aware：按區域本地化數據/密鑰。
審計日誌：WORM，Merkle切片，DSSE簽名。

13）運營： SLI/SLO和dashbords

• 每個路線/地區的可用性。
• 潛伏期p95（閱讀/寫作）。
• Webhook（收據）的成功率，交付時間差。
• Error-rate/Retry-rate.
• 1k查詢和egress的成本。

SLO（示例）：99。95%的可用性；p95 ≤ 120/250毫秒；webhooks ≥ 99。5%/5分鐘；P1 MTTR ≤ 60分鐘。

14）變更管理（發行/回扣）

藍綠色/金絲雀用於鎖和關鍵路線。
Ficheflagi用於不發布行為。
Expand→Migrate→Contract用於電路和付費。

Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.

文物：簽名的圖像/清單，版本註冊表。

15） SDK,客戶,「沙箱」

具有相同錯誤和後綴語義的官方SDK（TS/Java/Python/Go）。
帶有測試密鑰/證書和PSP/KYC/內容提供商模擬器的 Sandbox環境。
合同測試包含在SDK CI（夜間兼容性）中。

16）數據模型（簡化）

`api_key` `{id, tenant, scopes[], ttl, created_by}`

`rate_plan` `{tenant, quotas{route→cap}, burst, priority}`

`request_log` `{trace_id, route, actor, idempotency_key?, status, latency_ms, region, cost_unit}`

`webhook_receipt` `{event_id, endpoint, status, attempts, receipt_hash, signature}`

`policy` `{version, rules, signer, dsse}`

17) RACI

18）質量指標

Contract Drift：0「打破」更改而無需刪除。

Idempotency Error Rate: ≤ 0.01%.

Webhook Success: ≥ 99.5％，p95 ≤ 60秒差。
Auth Fail vs Abuse：惡意塊的份額，噪音≤目標級別。
Cost/1k：路線和區域監測（預算/上限）。
SDK Adoption：通過官方SDK的流量份額。

19）事件花花公子

Spike 429/限值：提高黃金的帽子,trottling「嘈雜」的鑰匙,與合作夥伴的聯系。
WebhookLag：增加鍛煉者/訓練營,優先排隊,暫時關閉可選的webhook。
PriceMismatch（目錄/FX/Tax）：版本匹配，高速緩存強制失效，工件回滾，補償。
PSP外觀：切換路線，隔離「灰色」交易，反射。
Compromise API密鑰：立即召回,輪換,審核過去30天。

20） iGaming/fintech特點

RTP/Limits API：僅聚合和配置文件版本；更改-收據。
付款/付款：202多個帶有簽名的webhooks；訂單密鑰的等效性。
附屬機構：轉換的厄運，爭議代管，簽名報告。
負責任的遊戲：展示限值和RG事件的「guardrails API」。

21）實施支票

• 描述了合同（OpenAPI/AsyncAPI），CI驗證和消費者測試。
• 針對關鍵路由配置OAuth2/OIDC、漏洞、JIT秘密和mTLS。
• 引入了Idementity、retrai、DLQ和檢疫。
• 限制/配額/優先級和差額。
• 遊標分段，一致性樣本「as_of」。
• 驗證和處置政策。
• Webhooks帶有簽名/收據，繼電器和dedup。
• 跟蹤/度量/標誌，SLO和符文。
• WORM日誌、DSSE簽名、Merkle切片。
• SDK、sandbox、模擬器、代碼示例和「如何」。

22) FAQ

為什麼202用於長途手術?

為了避免保持連接並通過webhook提供可靠的轉發/收據。

是否需要兩者：OpenAPI和AsyncAPI？
是：用於命令/查詢的同步；用於事件/狀態匹配的async。

如何避免破裂的變化？
「僅添加」規則，deprecate → observe → remove，客戶合同測試。

收據在哪裏？
在帶簽名的WORM區域中,「receipt_hash」返回給客戶端,並根據請求進行驗證。

摘要：通過API進行的操作是合同和運營的學科：嚴格的訪問模式和等效性，限制和版本，可觀察性和SLO，簽名和收據。添加沙盒和SDK-合作夥伴將快速、安全和可預測地集成,業務將擴展而不會損失質量和合規性。