API İşlemleri

(Bölüm: Operasyonlar ve Yönetim)

1) Amaç ve prensipler

API, ekosistemin "operasyonel katmanı'dır: Bir sözleşme yoluyla otomatikleştirilmeyen her şey manuel işe ve riske dönüşür.

• Sözleşme-ilk: ilk şartname (OpenAPI/JSON Schema/AsyncAPI), sonra uygulama.
• Varsayılan olarak güvenli: minimal kapsamlar, kısa TTL, karşılıklı TLS/imzalar.
• Gözlemlenebilir: uçtan uca izleme ve SLA metrikleri.
• Idempotent: Güvenli bir şekilde tekrar oynatın.
• Geriye doğru uyumlu: Değişiklikleri "kırmadan" evrim.
• Denetlenebilir: kriptografik olarak onaylanmış gerçekler (makbuzlar).

2) Sözleşme ve modeller (referans)

Senkronizasyon istekleri için OpenAPI; Etkinlikler/webhook'lar için AsyncAPI.
Her kaynakta gerekli alanlar'id ',' version ',' created _ at ',' updated _ at ',' tenant ',' region ',' trace _ id'dir.

Bir sözleşme parçası örneği

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) Kimlik doğrulama, yetkilendirme, kapsamlar

Kullanıcılar/ortaklar için OAuth2/OIDC istemci-kimlik bilgileri/JWT для S2S.
Kapsamlar/kaynak rolleri: 'ödemeler. Katalog yaz. ',' denetimini okuyun. İhracat '.
ReBAC: "mülkiyet yoluyla" erişim (kiracı/hesap/alt hesap).
JIT sırları: kısa ömürlü belirteçler, cihaz/alt ağ/bölge bağlama.
Kritik işlemler için cihaz duruşu ve mTLS (ödemeler, anahtarlar).

4) Idempotence ve "tam olarak bir kez"

Idempotency-Key (header) + TTL penceresinde '(key, account, route)'ile dedup.
Olayları yayınlamak için giden kutusu/CDC - garantili teslimat.
Tam olarak bir kez etkiler: yan etkiler bir işlem günlüğü aracılığıyla yakalanır; Tekrarlama aynı "makbuza" ('makbuz _ hash') yol açar.
Yeniden deneme ilkeleri: üstel geri çekilme, titreme, maksimum pencereler.

5) Sınırlar, kotalar, önceliklendirme

Hız sınırları: anahtar başına/kiracı/rota/bölge; "yumuşak" (429) ve "sert" (kesme).
Kotalar/bütçeler: aylık/günlük sınırlar, webhooks 'CotaCapReached'.
Adil kullanım: hizmet seviyesine göre kiracıların önceliği (Altın/Gümüş/Bronz).
Patlama tamponları: komşuların bozulması olmadan kısa patlamalar.

6) Pagination, filtreler, örnekler

İmleç tabanlı (kararlı sıralama по 'created _ at, id'), 'page _ size' ≤ 1000.
Günlükler/işlemler için zaman dilimli örnekler ('from', 'to', 'filigran').
DSL filtreleme: beyaz listeye alınmış поля, '? status =... & tenant =... & region =...'.
Tutarlılık ipuçları: API'leri raporlamak için 'snapshot _ at'/' as _ of'.

7) Sürüm oluşturma ve uyumluluk

SemVer: 'v1', 'v1. 1 '(uzantılar),' v2 '- yalnızca yeni yollarda/ad alanlarında.
Evrim kuralları: yalnızca alanları/değerleri ekleyin, pencereden "kullanımdan kaldırın".
Uyumluluk testleri: "Test olarak sözleşmeler" (tüketici odaklı).

8) Etkinlikler, web kitapları ve makbuzlar

AsyncAPI temaları/yükü/imzaları açıklar.

Başlık: HMAC/EdDSA, 'X-Signature', 'X-Nonce', 'X-Timestamp' başlıkları (dar pencere)

Makbuzlar: 'Receipt _ hash've kritik olaylarda DSSE imzası (ödemeler, RTP/limit değişiklikleri, fiyat listeleri).
Retrai ve dedup: 'idempotency _ key'/' event _ id'e göre idempotency.
DLQ/karantina: geçersiz/nedenleri ile tekrarlanan raporlar.

9) Gözlemlenebilirlik ve kalite

İzler: Ağ geçidi/iş etkinlikleri/web kitapları aracılığıyla zorunlu 'trace _ id/span _ id'.
Metrikler: kullanılabilirlik, p50/p95/p99, hata oranı, yeniden deneme oranı, 1k başına maliyet.
Günlükler: yapılandırılmış, sır yok/PII; 'tenant/region/version' labels.
SLO/uyarılar: SLO yönelimli koşullar ve otomatik çalıştırmalar (duraklatma/yeniden yönlendirme/geri alma).

10) Hatalar ve durum semantiği

2xx - başarı (asenkron işlemler için 202).
4xx - müşterinin hatası (422 - doğrulama, 409 - çatışma/idempotency, 429 - sınırları).
5xx - geçici sorunlar.
Hata gövdesi: 'kod', 'mesaj', 'trace _ id', 'ipucu', 'retry _ after? '.
Ortaklar için UX: Her hata için'ne yapmalı "tablosu.

11) Kod olarak politikalar (OPA/ABAC)

Merkezi yetkilendirme:'kim/ne/nerede/ne zaman/neden ".
Git'teki politikalar, kod incelemesi, CI testleri (uçuş öncesi: "Politika izin verecek mi? »).
SoD kontrolü: "ödeme oluştur" ≠ "onayla".

12) Güvenlik, gizlilik, uyumluluk

PII minimizasyonu: tokenizasyon/maskeler, yalnızca onaylanmış jablar yoluyla birincil erişim.
Sırlar: Kasa/KMS, kısa TTL, rotasyonlar; Paylaşılan sırların yasaklanması.
Şifreleme: mTLS/TLS 1. 3, AES-GCM dinlenme, HSTS/PKP uygun olduğunda.
Yargı yetkisi farkındalığı - Bölge başına veri/anahtarların yerelleştirilmesi.
Denetim günlükleri: WORM, Merkle dilimleri, DSSE imzaları.

13) Çalışma: SLI/SLO ve panolar

• Rota/bölge başına kullanılabilirlik.
• P95 gecikme süresi (okuma/yazma).
• Webhook'ların başarısı (makbuzlar), teslimat gecikmesi.
• Hata oranı/Yeniden deneme hızı.
• 1k istek ve çıkış başına maliyet.

SLO (örnek): 99. %95 kullanılabilirlik; P95 ≤ 120/250 ms; Webhooks ≥ 99. %5/5-dk; P1 MTTR ≤ 60 dk.

14) Değişim Yönetimi (Sürümler/Geri Dönüşler)

Geçitler ve kritik yollar için Mavi-Yeşil/Kanarya.
Serbest bırakma davranışı için Ficheflags.
Genişlet> Migrate> Şemalar ve yük için sözleşme.
Руны: Geri Alma Serbest Bırak, Bayrağı Devre Dışı Bırak, Yeniden Yönlendir, Önbelleği Temizle.
Artifaktlar: imzalı görüntüler/manifestolar, sürüm kaydı.

15) SDK, istemciler, sanal alanlar

Aynı hataya sahip resmi SDK'lar (TS/Java/Python/Go) ve anlambilimi yeniden ayır.
Test tuşları/sertifikaları ve PSP/KYC/içerik sağlayıcı simülatörleri ile sandbox ortamları.
Sözleşme testleri CI SDK, gece uyumluluk dahildir.

16) Veri modeli (basitleştirilmiş)

'api _ key' '{id, kiracı, kapsamlar [], tl, created_by}'

'rate _ plan' '{kiracı, kotalar {rota _ cap}, patlama, öncelik}'

'request _ log' '{trace _ id, rota, aktör, idempotency_key?, durum, latency_ms, bölge, cost_unit}'

'webhook _ receipt' '{event _ id, uç nokta, durum, girişimler, receipt_hash, imza}'

'politika' '{sürüm, kurallar, imzalayan, dsse}'

17) RACI

18) Kalite metrikleri

Sözleşme Drift: 0 "kırma" değişikliklerini kullanımdan kaldırmadan.
Idempotency Hata Oranı: ≤ 0. 01%.
Webhook Başarı: ≥ 99. %5, lag p95 ≤ 60 s.
Auth Fail vs Abuse: Kötü amaçlı blokların paylaşımı, gürültü ≤ hedef seviyesi.
Cost/1k: rotalara ve bölgelere göre kontrol (bütçeler/sınır uyarıları).
Benimseme SDK: resmi SDK'lar aracılığıyla trafik payı.

19) Olay oyun kitapları

Spike 429/limits: Gold için yükseltme sınırı, "gürültülü" tuşları kısma, bir ortakla bağlantı.
WebhookLag: Çalışanları/partileri artırın, kuyruklara öncelik verin, isteğe bağlı web kitaplarını geçici olarak kapatın.
PriceMismatch (katalog/FX/Vergi): sürüm uzlaştırma, önbellek kuvveti sakatlığı, artefakt geri dönüşü, tazminat.
PSP Kesintisi: rota değiştirme, "gri" işlemlerin karantinası, yeniden oynatma.
Uzlaşma API anahtarı: derhal geri çağırma, rotasyon, son 30 günün denetimi.

20) iGaming/fintech'in özgüllüğü

RTP/Limits API: yalnızca agregalar ve profil sürümleri; değişiklikler - makbuzlarla.
Ödemeler/ödemeler: 202 + imzalı webhook; Anahtar idempotency sipariş edin.
İştirakler: dönüşüm tahsisi, anlaşmazlıklar için emanet, imzalı raporlar.
Sorumlu oyun: Sınırlar ve RG olayları için "korkuluklar API'sini" açığa çıkarın.

21) Uygulama kontrol listesi

• Açıklanan sözleşme (OpenAPI/AsyncAPI), CI doğrulama ve tüketici testleri.
• Kritik yollar için yapılandırılmış OAuth2/OIDC, kapsamlar, JIT sırları ve mTLS.
• Idempotency, retrai, DLQ ve karantina tanıtıldı.
• Kapaklar/Kotalar/Öncelikler ve Uyarılar.
• İmleç sayfalama,'as _ of 'tutarlı örnekler.
• Sürüm Oluşturma ve Kullanımdan Kaldırma Politikası.
• İmzalar/makbuzlar, tekrar oynatma ve dedup ile Webhooks.
• İzleme/metrikler/günlükler, SLO ve rünler.
• WORM günlükleri, DSSE imzaları, Merkle dilimleri.
• SDK, sandbox, simülatörler, kod örnekleri ve nasıl yapılır.

22) SSS

Neden uzun operasyonlar için 202?
Bağlantıyı tutmamak ve webhook üzerinden güvenilir bir yeniden ödeme/makbuz sağlamak için.

Hem OpenAPI hem de AsyncAPI'ye ihtiyacınız var mı?
Evet: komutlar/istekler için senkronizasyon, olaylar/durum görüşmesi için async.

Değişiklikleri kırmak nasıl önlenir?
Add-only kuralı, amortisman - gözlemle - kaldır, müşteri test sözleşmesi.

Makbuzlar nerede saklanır?
İmzaları olan bir WORM bölgesinde; 'receipt _ hash' istemciye iade edilir ve istek üzerine kontrol edilir.

Özet: API üzerinden yapılan işlemler sözleşme ve işlem disiplinidir: sıkı erişim modeli ve idempotency, limitler ve sürümler, gözlemlenebilirlik ve SLO, imzalar ve makbuzlar. Sanal alanlar ve SDK'lar ekleyin - iş ortakları hızlı, güvenli ve öngörülebilir bir şekilde entegre olur ve işletmeler kalite veya uyumluluk kaybı olmadan ölçeklenir.