API interfeysi vasitəsilə əməliyyatlar

(Bölmə: Əməliyyatlar və İdarəetmə)

1) Təyinat və prinsiplər

API ekosistemin «əməliyyat qatıdır»: müqavilə vasitəsilə avtomatlaşdırılmayan hər şey əl işi və risklərə çevrilir.

• Contract-first: əvvəlcə spesifikasiya (OpenAPI/JSON Schema/AsyncAPI), sonra həyata.
• Secure-by-default: minimum cups, qısa TTL, myutual-TLS/imzalar.
• Observable: end-to-end izləmə və SLA metrikası.
• Idempotent: təkrar təhlükəsiz.
• Backwards-compatible: «qırıcı» dəyişikliklər olmadan təkamül.
• Auditable: kriptoqrafik təsdiqlənmiş faktlar (qəbzlər).

2) Müqavilə və modellər (referans)

sync-sorğular üçün OpenAPI; Action/Webhook üçün AsyncAPI.
Hər bir resursda məcburi sahələr: 'id', 'version', 'created _ at', 'updated _ at', 'tenant', 'region', 'trace _ id'.

Müqavilə fraqmentinin nümunəsi

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) Autentifikasiya, avtorizasiya, satınalma

OAuth2/OIDC/partnyorlar üçün; client-credentials/JWT для S2S.
Satınalmalar/resurs rolları: 'payments. write`, `catalog. read`, `audit. export`.
ReBAC: «sahiblik» (tenant/hesab/sab-hesab).
JIT sirləri: qısamüddətli tokenlər, cihaz/alt şəbəkə/region.
Kritik əməliyyatlar (ödənişlər, açarlar) üçün Device posture & mTLS.

4) İdempotentlik və «düz bir dəfə»

Idempotency-Key (başlıq) + TTL pəncərəsində '(key, account, route)' dedup.
Hadisələrin yayımlanması üçün Outbox/CDC - zəmanətli çatdırılma.
Exactly-once-effects: yan təsirləri əməliyyat jurnalı vasitəsilə qeyd olunur; təkrar eyni «qəbz» gətirib çıxarır ('receipt _ hash').
Retry siyasətləri: eksponensial geri dönüş, jitter, maksimum pəncərələr.

5) Limitlər, kvotalar, prioritetləşdirmə

Rate limits: per-key/tenant/route/region; «yumşaq» (429) və «sərt» (kəsmə).
Kvotalar/büdcələr: aylıq/gündəlik kaplar, vebhuklar 'QuotaCapReached'.
Fair-use: xidmət səviyyəsinə görə tenantların prioriteti (Gold/Silver/Bronze).
Burst-buferlər: qonşuların deqradasiyası olmadan qısa partlayışlar.

6) Pagination, filtrlər, nümunələr

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.
Jurnallar/əməliyyatlar üçün Time-sliced nümunələri ('from', 'to', 'watermark').
Filtering DSL: whitelisted поля, `?status=...&tenant=...&region=...`.
Consistency hints: reporting API üçün 'snapshot _ at '/' as _ of'.

7) Version və uyğunluq

SemVer: `v1`, `v1. 1 '(uzantıları),' v2 '- yalnız yeni yollar/neyspeaks.
Təkamül qaydaları: yalnız sahələr/qiymətlər əlavə, pəncərə vasitəsilə «deprecate → remove».
Compatibility tests: «müqavilələr-kimi-testlər» (consumer-driven).

8) Hadisələr, vebhuk və qəbzlər

AsyncAPI mövzuları/payload/imzaları təsvir edir.
İmza: HMAC/EdDSA, başlıqlar 'X-Signature', 'X-Nonce', 'X-Timestamp' (dar pəncərə).
Qəbzlər (receipts): kritik hadisələrdə 'receipt _ hash' və DSSE imzası (ödənişlər, RTP/limitlərdəki dəyişikliklər, qiymət vərəqləri).
Retray və dedup: idempotency _ key '/' event _ id '.
DLQ/karantin: səbəbləri ilə nevalid/təkrar mesajlar.

9) Müşahidə və keyfiyyət

Traces: məcburi 'trace _ id/span _ id' şlüz vasitəsilə/biznes hadisələri/vebhuk.
Metrics: əlçatanlıq, p50/p95/p99, error-rate, retry-rate, cost per 1k.
Logs: strukturlaşdırılmış, heç bir gizli/PII; 'tenant/region/version' etiketləri.
SLO/alertlər: SLO yönümlü şərtlər və avto-run (pause/re-route/rollback).

10) Səhvlər və status semantikası

2xx - uğur (202 asenxron əməliyyatlar üçün).
4xx - müştərinin günahı (422 - validasiya, 409 - münaqişə/idempotentlik, 429 - limitlər).
5xx - müvəqqəti problemlər.
Səhv bədən: 'code', 'message', 'trace _ id', 'hint', 'retry _ after?'.
Tərəfdaşlar üçün UX: Hər bir səhv üçün «nə etmək» cədvəli.

11) Kod kimi siyasət (OPA/ABAC)

Mərkəzləşdirilmiş avtorizasiya: «kim/nə/harada/nə vaxt/nə üçün».
Git siyasətləri, kod review, CI testləri (pre-flight: "siyasət icazə verəcəkmi? »).
SoD-çek: «ödəniş yaratmaq» ≠ «təsdiq etmək».

12) Təhlükəsizlik, gizlilik, uyğunluq

PII-minimallaşdırma: tokenizasiya/maskalar, birinciyə yalnız təsdiq edilmiş joblar vasitəsilə giriş.
Sirləri: Vault/KMS, qısa TTL, rotasiya; shared-secrets qadağan.
Şifrələmə: mTLS/TLS 1. 3, uyğun olduğu AES-GCM at-rest, HSTS/PKP.
Jurisdiction-aware: məlumatların/açarların lokalizasiyası per region.
Audit jurnalları: WORM, Merkle, DSSE imzaları.

13) Əməliyyat: SLI/SLO və dashboard

• per-route/region mövcudluğu.
• Gecikmə p95 (read/write).
• Vebhukların müvəffəqiyyəti (qəbz), çatdırılma gecikməsi.
• Error-rate/Retry-rate.
• Cost per 1k sorğular və egress.

SLO (nümunə): 99. 95% mövcudluğu; p95 ≤ 120/250 ms; webhucks ≥ 99. 5 %/5-dəq; P1 MTTR ≤ 60 dəq.

14) Dəyişikliyin idarə edilməsi (buraxılışlar/geri çəkilmələr)

Şlyuzlar və kritik marşrutlar üçün Blue-Green/Canary.
azad olmadan davranış üçün fitness.
Sxemlər və payload üçün Expand → Migrate → Contract.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
Artefaktlar: imzalanmış şəkillər/manifestlər, versiya reyestri.

15) SDK, müştərilər, «qum qutuları»

Eyni səhv və retraj semantikası ilə rəsmi SDK (TS/Java/Python/Go).
Test açarları/sertifikatları və PSP/KYC/məzmun provayderlərinin simulyatorları ilə Sandbox mühiti.
Contract-tests SDK CI daxil, nightly-uyğunluq.

16) Data modeli (sadələşdirilmiş)

`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) Keyfiyyət metrikası

Contract Drift: 0 «pozucu» dəyişiklik deprequit olmadan.
Idempotency Error Rate: ≤ 0. 01%.
Webhook Success: ≥ 99. 5%, lag p95 ≤ 60 s.
Auth Fail vs Abuse: zərərli blokların payı, səs-küy ≤ hədəf səviyyəsi.
Cost/1k: marşrutlar və regionlar üzrə nəzarət (büdcələr/kaps-alertlər).
SDK Adoption: rəsmi SDK vasitəsilə trafik payı.

19) Hadisə pleybukları

Spike 429/limitləri: Gold üçün cap qaldırmaq, «səs-küylü» açarları Trottling, tərəfdaş ilə əlaqə.
WebhookLag: workers/batches artırmaq, növbə prioritet, müvəqqəti olaraq isteğe bağlı webhucks söndürmək.
PriceMismatch (catalog/FX/Tax): versiyaların müqayisəsi, fors-cash əlilliyi, artefaktın geri qaytarılması, kompensasiya.
PSP Outage: keçid marşrutu, karantin «boz» əməliyyatlar, replikalar.
Compromise API-key: dərhal geri çağırma, rotasiya, son 30 gün audit.

20) iGaming/Fintech xüsusiyyətləri

RTP/Limits API: yalnız aqreqatlar və profil versiyaları; dəyişikliklər - qəbzlərlə.
Ödənişlər/ödənişlər: 202 + imzalı vebhuk; sifariş açarına idempotentlik.
Affiliates: deadup konversiyalar, mübahisələr üçün eskrou, imzalanmış hesabatlar.
Məsuliyyətli oyun: limitlər və RG hadisələri üçün «guardrails API» sərgiləyin.

21) Giriş çek siyahısı

• Müqavilə (OpenAPI/AsyncAPI), CI-validasiya və consumer-tests təsvir edilmişdir.
• Kritik marşrutlar üçün OAuth2/OIDC, cups, JIT sirləri və mTLS konfiqurasiya.
• İdempotentlik, retraj, DLQ və karantin tətbiq edilmişdir.
• Limitlər/kvotalar/prioritetlər və qapaq riskləri.
• Pagination kursor, konsistent nümunələri 'as _ of'.
• Version və Deprecation-siyasət.
• Imzalar/Qəbzlər, Reples və Dedup ilə Vebhuke.
• Tracking/Metrics/Logi, SLO və Runes.
• WORM jurnalları, DSSE imzaları, Merkle dilləri.
• SDK, sandbox, simulyatorlar, kod nümunələri və «how-to».

22) FAQ

Niyə 202 uzun əməliyyatlar üçün?
Əlaqəni saxlamamaq və etibarlı retray/qəbz təmin etmək üçün.

Hər ikisi lazımdır: OpenAPI və AsyncAPI?
Bəli: komandalar/sorğular üçün sync, hadisələr/vəziyyətlərin əlaqələndirilməsi üçün async.

Pozucu dəyişikliklərdən necə qaçmaq olar?
«Yalnız əlavələr» qaydası, deprecate → observe → remove, müştərilərin müqavilə testləri.

Qəbzlər harada saxlanılır?
WORM zonasında imzalarla; 'receipt _ hash' müştəriyə qaytarılır və sorğu əsasında yoxlanılır.

Xülasə: API vasitəsilə əməliyyatlar müqavilə və istismar intizamıdır: ciddi giriş və idempotentlik modeli, limitlər və versiyalar, müşahidə və SLO, imzalar və qəbzlər. Qum qutusu və SDK əlavə edin - və tərəfdaşlar sürətli, təhlükəsiz və proqnozlaşdırıla bilən şəkildə inteqrasiya olunacaq və biznes keyfiyyət və uyğunluq itkisi olmadan genişlənəcəkdir.