API interfeysi orqali operatsiyalar

(Bo’lim: Operatsiyalar va Boshqaruv)

1) Vazifasi va prinsiplari

API - bu ekotizimning «operatsion qatlami»: shartnoma orqali avtomatlashtirilmagan hamma narsa qo’lda ishlashga va xatarlarga aylanadi.

• Contract-first: avval spetsifikatsiya (OpenAPI/JSON Schema/AsyncAPI), so’ngra amalga oshirish.
• Secure-by-default: minimal shoplar, qisqa TTL, myutal-TLS/imzolar.
• Observable: end-to-end trastirovkasi va SLA metrikasi.
• Idempotent: takrorlash xavfsiz.
• Backwards-compatible: «buzuvchi» o’zgarishlarsiz evolyutsiya.
• Auditable: kriptografik tasdiqlangan faktlar (kvitansiyalar).

2) Kontrakt va modellar (referens)

sync soʻrovlari uchun OpenAPI; Hodisa/vebxuk uchun AsyncAPI.
Har bir resursdagi majburiy maydonlar:’id’,’version’,’created _ at’,’updated _ at’,’tenant’,’region’,’trace _ id’.

Kontrakt parchasining namunasi

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) Autentifikatsiya, avtorizatsiya, sotib olish

foydalanuvchilar/sheriklar uchun OAuth2/OIDC; client-credentials/JWT для S2S.
Xarid/resurs rollari:’payments. write`, `catalog. read`, `audit. export`.
ReBAC: «egalik qilish» (tenant/akkaunt/sab-akkaunt).
JIT sirlari: qisqa yashaydigan tokenlar, qurilmaga/kichik tarmoqlarga/mintaqaga bog’lash.
Device posture & mTLS kritik operatsiyalar uchun (toʻlovlar, kalitlar).

4) Idempotentlik va «bir marta»

Idempotency-Key (sarlavha) + TTL-oynada’(key, account, route)’bo’yicha dedup.
Voqealarni chop etish uchun Outbox/CDC - kafolatlangan yetkazib berish.
Exactly-once-effects: nojo’ya ta’sirlar tranzaksiya jurnali orqali qayd etiladi; takrorlash xuddi shu «kvitansiya» (’receipt _ hash’) ga olib keladi.
Retry-siyosati: eksponensial back-off, jitter, maksimal derazalar.

5) Limitlar, kvotalar, ustuvorlik

Rate limits: per-key/tenant/route/region; «yumshoq» (429) va «qattiq» (kesish).
Kvotalar/budjetlar: oylik/sutkalik kaplar, vebxuklar’QuotaCapReached’.
Fair-use: servis darajasi boʻyicha tenantlarning ustuvorligi (Gold/Silver/Bronze).
Burst-buferlar: qo’shnilarni buzmasdan qisqa portlashlar.

6) Paginatsiya, filtrlar, namunalar

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.
Jurnallar/tranzaksiyalar uchun Time-sliced tanlov (’from’,’to’,’watermark’).
Filtering DSL: whitelisted поля, `?status=...&tenant=...&region=...`.
Consistency hints:’snapshot _ at ’/’ as _ of’uchun reporting API.

7) Versiyalash va muvofiqlik

SemVer: `v1`, `v1. 1’(kengaytmalar),’v2’- faqat yangi yo’llar/neyspeyslar bo’yicha.
Evolyutsiya qoidalari: faqat oynadan «deprecate → remove» qoʻshish.
Compatibility tests: «kontraktlar-testlar» (consumer-driven).

8) Voqealar, vebxuklar va kvitansiyalar

AsyncAPI imzo/payload mavzularini tasvirlaydi.
Imzo: HMAC/EdDSA, sarlavhalar «X-Signature», «X-Nonce», «X-Timestamp» (tor oyna).
Kvitansiyalar (receipts):’receipt _ hash’va DSSE-muhim voqealarga imzo qo’yish (to’lovlar, RTP/limitlar o’zgarishi, prays-varaqlar).
Retrai va dedup:’idempotency _ key ’/’ event _ id’.
DLQ/karantin: sabablari bilan nolid/takroriy xabarlar.

9) Kuzatuvchanlik va sifat

Traces: majburiy’trace _ id/span _ id’.
Metrics: foydalanish imkoniyati, p50/p95/p99, error-rate, retry-rate, cost per 1k.
Logs: strukturalangan, sirsiz/PII; ’tenant/region/version’ belgilari.
SLO/alertlar: SLO-yo’naltirilgan shartlar va avto-runlar (pause/re-route/rollback).

10) Xatolar va maqomlar semantikasi

2xx - muvaffaqiyat (202 asinxron operatsiyalar uchun).
4xx - mijozning aybi (422 - validatsiya, 409 - ziddiyat/idempotentlik, 429 - limitlar).
5xx - vaqtinchalik muammolar.
Xatoning tanasi:’code’,’message’,’trace _ id’,’hint’,’retry _ after?’.
Hamkorlar uchun UX: har bir xato uchun «nima qilish kerak» jadvali.

11) Siyosat-kod sifatida (OPA/ABAC)

Markazlashtirilgan avtorizatsiya: «kim/nima/qaerda/qachon/nima uchun».
Git, kod-revyu, CI-testlar (pre-flight: "siyosat ruxsat beradimi? »).
SoD-chek: «to’lovni yaratish» ≠ «tasdiqlash».

12) Xavfsizlik, maxfiylik, komplayens

PII-minimallashtirish: tokenizatsiya/niqoblar, birlamchi ishga kirish faqat ma’qullangan joblar orqali amalga oshiriladi.
Sirlar: Vault/KMS, qisqa TTL, rotatsiyalar; shared-sirlarni taqiqlash.
Shifrlash: mTLS/TLS 1. 3, AES-GCM at-rest, HSTS/PKP o’rinli.
Jurisdiction-aware: per region.
Audit jurnallari: WORM, Merkle-seslar, DSSE-imzolar.

13) Foydalanish: SLI/SLO va dashbordlar

• per-route/region.
• Latentlik p95 (read/write).
• Vebxuklarning muvaffaqiyati (kvitansiya), yetkazib berish muddati.
• Error-rate/Retry-rate.
• Cost per 1k soʻrovlar va egress.

SLO (misol): 99. 95% foydalanish; p95 ≤ 120/250 ms; vebxuki ≥ 99. 5 %/5-min; P1 MTTR ≤ 60 min.

14) O’zgartirishlarni boshqarish (relizlar/qaytishlar)

shlyuzlar va muhim yo’nalishlar uchun Blue-Green/Canary.
Relizsiz xatti-harakatlar uchun ficheflaglar.
Sxemalar va payload uchun Expand → Migrate → Contract.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
Artefaktlar: imzolangan tasvirlar/manifestlar, versiyalar reyestri.

15) SDK, mijozlar, «qum qutilari»

Rasmiy SDK (TS/Java/Python/Go) bir xil xato va retraj semantikasiga ega.
Sinov kalitlari/sertifikatlari va PSP/KYC/kontent provayderlarining simulyatorlari bilan Sandbox-muhit.
Contract-tests SDK CI, nightly-moslashuvchanlikka kiritilgan.

16) Ma’lumotlar modeli (soddalashtirilgan)

`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) Sifat metrikasi

Contract Drift: 0 «buzuvchi» oʻzgarishlar.
Idempotency Error Rate: ≤ 0. 01%.

Webhook Success: ≥ 99. 5%, lag p95 ≤ 60 s

Auth Fail vs Abuse: zararli bloklar ulushi, maqsadli darajadagi ≤ shovqin.
Cost/1k: yo’nalishlar va hududlar bo’yicha nazorat (budjetlar/kap-alertlar).
SDK Adoption: rasmiy SDK orqali trafik ulushi.

19) Hodisalar pleybuklari

Spike 429/limitlar: Gold uchun qopqoq, shovqinli kalitlar trottling, sherik bilan aloqa.
WebhookLag: mashg’ulotlarni ko’paytirish, navbatlarni ustuvor qilish, ixtiyoriy vebxuklarni vaqtincha o’chirish.
PriceMismatch (catalog/FX/Tax): versiyalarni solishtirish, keshning fors-nogironligi, artefaktning qaytarilishi, kompensatsiyalar.
PSP Outage: yo’nalishni o’zgartirish, «kulrang» tranzaksiyalar, replyatsiyalar karantini.
Compromise API-key: so’nggi 30 kun ichida darhol chaqirib olish, rotatsiya, audit.

20) iGaming/fintech xususiyatlari

RTP/Limits API: faqat agregatlar va profillar versiyasi; o’zgartirishlar - kvitansiyalar bilan.
To’lovlar/to’lovlar: 202 + imzolar bilan vebxuklar; buyurtmaning kalitga muvofiqligi.
Affiliatlar: konversiyalarning dedupi, nizolar uchun eskrou, imzolangan hisobotlar.
Mas’uliyatli o’yin: limitlar va RG tadbirlari uchun «guardrails API» ni namoyish qiling.

21) Joriy etish chek-varaqasi

• Shartnoma (OpenAPI/AsyncAPI), CI-validatsiya va consumer-tests tavsiflangan.
• Tanqidiy yo’nalishlar uchun OAuth2/OIDC, xarid, JIT sirlari va mTLS moslashtirilgan.
• Idempotentlik, retray, DLQ va karantin joriy etildi.
• Kaplar bo’yicha limitlar/kvotalar/ustuvorliklar va alertlar.
• Kursorlar tomonidan paginatsiya,’as _ of’konsistent namunalari.
• Versiyalash va Deprecation-siyosat.
• Imzolar/kvitansiyalar, gaplar va deduplar bilan vebxuklar.
• Trastirovka/metrika/loglar, SLO va runalar.
• WORM jurnallari, DSSE imzolari, Merkle qismlari.
• SDK, sandbox, simulyatorlar, kod namunalari va «how-to».

22) FAQ

Nima uchun 202 uzoq operatsiyalar uchun?
Ulanmaslik va ishonchli retray/kvitansiyani vebxuk orqali taʼminlash uchun.

Ikkalasi ham kerakmi: OpenAPI va AsyncAPI?
Ha: buyruqlar/soʻrovlar uchun sync, hodisalar/holatlar uchun async.

Buzgʻunchi oʻzgarishlardan qanday qochish mumkin?
«Faqat qo’shish» qoidasi, deprecate → observe → remove, mijozlarning kontrakt-testlari.

Kvitansiyalarni qayerda saqlash kerak?
WORM zonasida imzolar bilan’receipt _ hash’mijozga qaytariladi va so’rov bo’yicha solishtiriladi.

Xulosa: API orqali operatsiyalar - bu kontrakt va foydalanish intizomi: kirish va idempotentlikning qat’iy modeli, limitlar va versiyalar, kuzatuv va SLO, imzo va kvitansiyalar. Qum qutisi va SDK qo’shing - va sheriklar tez, xavfsiz va oldindan aytib bo’lmaydigan tarzda integratsiyalashadi, biznes esa sifat va komplayensni yo’qotmasdan kengaytiriladi.