API arkaly amallar

(Bölüm: Amallar we Dolandyryş)

1) Bellenilmegi we ýörelgeleri

API ekosistemanyň "iş gatlagy": şertnama arkaly awtomatlaşdyrylmadyk hemme zat el işine we töwekgelçilige öwrülýär.

• Contract-first: ilki spesifikasiýa (OpenAPI/JSON Shema/AsyncAPI), soňra durmuşa geçirmek.
• Secure-by-default: iň az satyn almak, gysga TTL, aýdym-saz-TLS/gollar.
• Observable: end-to-end tracking & metrics SLA.
• Idempotent: gaýtalamak ygtybarly.
• Backwards-compatible: "döwýän" üýtgeşmeler bolmazdan ewolýusiýa.
• Auditable: kriptografiki taýdan tassyklanan faktlar (kwitansiýalar).

2) Şertnama we modeller (salgylanma)

sync-soraglar üçin OpenAPI; Wakalar/webhuklar üçin AsyncAPI.
Her çeşmede hökmany meýdanlar: 'id', 'version', 'created _ at', 'updated _ at', 'tenant', 'region', 'trace _ id'.

Şertnamanyň bölekleriniň mysaly

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) Tassyklamak, ygtyýarlandyrmak, satyn almak

OAuth2/OIDC/hyzmatdaşlar üçin; client-credentials/JWT для S2S.
Satyn almalar/çeşme rollary: 'payments. write`, `catalog. read`, `audit. export`.
ReBAC: "eýeçilik boýunça" giriş (tenant/hasap/sab-hasap).
JIT-syrlar: gysga ömürli bellikler, enjamy/kiçi ulgamy/sebiti baglanyşdyrmak.
Möhüm amallar üçin Device posture & mTLS (tölegler, açarlar).

4) Idempotentlik we "edil bir gezek"

Idempotency-Key (sözbaşy) + TTL-penjirede '(key, account, route)' boýunça dedup.
Wakalary çap etmek üçin Outbox/CDC - kepillendirilen eltip bermek.
Exactly-once-effects: zyýanly täsirleri geleşik magazineurnaly arkaly ýazylýar; gaýtalanmagy şol bir "kwitansiýa" ('receipt _ hash') sebäp bolýar.
Retry-syýasatlar: eksponensial arka, jitler, iň ýokary penjireler.

5) Çäklendirmeler, kwotalar, ileri tutulýan ugurlar

Rate limits: per-key/tenant/route/region; "ýumşak" (429) we "gaty" (kesmek).
Kwotalar/býudjetler: aýlyk/gündelik kaplar, webhuklar 'QuotaCapReached'.
Fair-use: hyzmat derejesi boýunça tenantlaryň ileri tutulmagy (Gold/Silver/Bronze).
Burst-buferler: goňşulary zaýalanmazdan gysga partlamalar.

6) Paginasiýa, süzgüçler, nusgalar

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.
Theurnallar/amallar üçin wagt-sliced ('from', 'to', 'watermark').
Filtering DSL: whitelisted поля, `?status=...&tenant=...&region=...`.
Consistency hints: 'snapshot _ at '/' as _ of' raporting API üçin.

7) Wersiýalaşdyrmak we gabat gelmek

SemVer: `v1`, `v1. 1 '(giňeltmek),' v2 '- diňe täze ýollar/neýspeysler boýunça.
Ewolýusiýa düzgünleri: diňe penjireden "deprecate → remove" goşmak.
Compatibility tests: "şertnamalar-ýaly-synaglar" (consumer-driven).

8) Wakalar, webhuklar we kwitansiýalar

AsyncAPI/payload/gollaryň mowzuklaryny beýan edýär.
Goly: HMAC/EdDSA, "X-Signature", "X-Nonce", "X-Timestamp" sözbaşylary (dar penjire).
Kwitansiýalar (receipts): 'receipt _ hash' we DSSE-möhüm wakalarda gol (tölegler, RTP/çäklerdäki üýtgeşmeler, baha sahypalary).
Retrailer we dedup: 'idempotency _ key '/' event _ id'.
DLQ/karantin: sebäpleri bilen galid däl/gaýtalanýan habarlar.

9) Gözegçilik edilişi we hili

Traces: hökmany 'trace _ id/span _ id' şlýuz/iş wakalary/webhuklar arkaly.
Metrics: elýeterlilik, p50/p95/p99, error-rate, retry-rate, cost per 1k.
Logs: gurluşly, syrsyz/PII; 'tenant/region/version' bellikleri.
SLO/alertler: SLO-gönükdirilen şertler we awto-runlar (pause/re-route/rollback).

10) Statuslaryň ýalňyşlyklary we semantikasy

2xx - üstünlik (202 asinxron amallary üçin).
4xx - müşderiniň günäsi (422 - tassyklama, 409 - gapma-garşylyk/idempotentlik, 429 - çäklendirmeler).
5xx - wagtlaýyn meseleler.
Hatanyň bedeni: 'code', 'message', 'trace _ id', 'hint', 'retry _ after?'.
Hyzmatdaşlar üçin UX: Her ýalňyşlyk üçin "näme etmeli" tablisasy.

11) Kodly syýasatlar (OPA/ABAC)

Merkezleşdirilen ygtyýarnama: "kim/näme/nirede/haçan/näme üçin".
Syýasatçylar Git, kod-revyu, CI-synaglar (pre-flight: "syýasata rugsat berermi? »).
SoD-çek: "töleg döretmek" ≠ "tassyklamak".

12) Howpsuzlyk, gizlinlik, gabat gelmek

PII-minimalizasiýa: tokenizasiýa/maskalar, başlangyç nokada diňe tassyklanan joblar arkaly girmek.
Syrlar: Vault/KMS, gysga TTL, aýlawlar; shared-syrlary gadagan etmek.
Şifrlemek: mTLS/TLS 1. 3, AES-GCM at-rest, HSTS/PKP ýerlikli.
Jurisdiction-aware: per region.
Audit žurnallary: WORM, Merkle-bölekler, DSSE-gollar.

13) Amal: SLI/SLO we daşbordlar

• per-route/region elýeterliligi.
• Gizlinlik p95 (read/write).
• Webhuklaryň (kwitansiýanyň) üstünligi, gowşuryş gijikdirmesi.
• Error-rate/Retry-rate.
• Cost per 1k soraglar we egress.

SLO (mysal): 99. 95% elýeterlilik; p95 ≤ 120/250 ms; webhuklar ≥ 99. 5 %/5-min; P1 MTTR ≤ 60 minut.

14) Üýtgetmeleri dolandyrmak (goýbermek/yzyna gaýtarmak)

Şlýuzlar we möhüm ugurlar üçin Blue-Green/Canary.
Çykyş etmezden özüni alyp barmak üçin fiçeflaglar.
Shemalar we töleg üçin Expand → Migrate → Contract.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
Artefaktlar: gol çekilen şekiller/manifestler, wersiýalaryň sanawy.

15) SDK, müşderiler, "gum gutulary"

Resmi SDK (TS/Java/Python/Go).
Synag açarlary/şahadatnamalary we PSP/KYC/mazmun üpjün edijileriniň simulýatorlary bolan Sandbox gurşawy.
Contract-tests SDK CI, nightly-gabat gelmek goşuldy.

16) Maglumatlaryň nusgasy (ýönekeýleşdirilen)

`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) Hil ölçegleri

Contract Drift: 0 "bozýan" üýtgeşmeler

Idempotency Error Rate: ≤ 0. 01%.
Webhook Success: ≥ 99. 5%, лаг p95 ≤ 60 s.
"Auth Fail vs Abuse": zyýanly bloklaryň paýy, maksat derejesi ≤ ses.
Cost/1k: ugurlar we sebitler boýunça gözegçilik (býudjetler/kap-alertler).
SDK Adoption: resmi SDK arkaly traffigiň paýy.

19) Wakalaryň pleýbuklary

Spike 429/çäkleri: Gold üçin gapagy, "şowhunly" açarlaryň trottlingini, hyzmatdaş bilen aragatnaşygy ýokarlandyrmak.
WebhookLag: workerleri/batchleri köpeltmek, nobatlary ileri tutmak, goşmaça webhuklary wagtlaýyn öçürmek.
PriceMismatch (catalog/FX/Tax): wersiýalary deňeşdirmek, nagt pullary ýeňip geçmek, artefaktyň yzyna gaýtarylmagy, öwezini dolmak.
PSP Outage: marşruty üýtgetmek, "çal" amallaryň karantini, bellikler.
Compromise API-key: derrew yzyna almak, aýlanmak, soňky 30 günüň barlagy.

20) iGaming/fintech aýratynlyklary

RTP/Limits API: diňe agregatlar we profilleriň wersiýalary; üýtgeşmeler - kwitansiýalar bilen.
Tölegler/tölegler: 202 + gollar bilen webhuklar; sargytyň açary üçin idempotentlik.
Affiliates: öwrülişikleriň dedupy, jedeller üçin eskrow, gol çekilen hasabatlar.
Jogapkär oýun: çäkler we RG wakalary üçin "guardrails API" -ni görkeziň.

21) Girizmegiň çek-sanawy

• Şertnama beýan edildi (OpenAPI/AsyncAPI), CI-tassyklama we consumer-tests.
• Möhüm ugurlar üçin OAuth2/OIDC, satyn alyş, JIT syrlary we mTLS sazlandy.
• Idempotentlik, retralar, DLQ we karantin girizildi.
• Kapasalar boýunça çäkler/kwotalar/ileri tutulýan ugurlar we töwekgelçilikler.
• Kursorlar tarapyndan paginasiýa, 'as _ of' konsistent nusgalary.
• Wersiýalaşdyrmak we Deprecation-syýasat.
• Gollary/kwitansiýalary, bellikleri we dedupy bolan webhuklar.
• Tracking/Metrics/Logy, SLO we Runes.
• WORM magazinesurnallary, DSSE gollary, Merkle bölekleri.
• SDK, sandbox, simulýatorlar, kod mysallary we "how-to".

22) FAQ

Näme üçin 202 uzak amallar üçin?
Baglanyşygy saklamazlyk we webhuk arkaly ygtybarly retrai/kwitansiýany üpjün etmek üçin.

Ikisi hem zerurmy: OpenAPI we AsyncAPI?
Hawa: sync buýruklar/soraglar üçin, async wakalar/ýagdaýlary utgaşdyrmak üçin.

Döwüji üýtgeşmelerden nädip gaça durmaly?
"Diňe goşmak" düzgüni, deprecate → observe → remove, müşderileriň şertnama-synaglary.

Kwitansiýalary nirede saklamak?
WORM zonasynda gollar bilen; 'receipt _ hash' müşderä gaýtarylýar we haýyş boýunça barlanýar.

Gysgaça mazmuny: API arkaly amallar - şertnamanyň we ekspluatasiýanyň düzgüni: elýeterliligiň we idempotentligiň berk modeli, çäkleri we wersiýalary, syn edilmegi we SLO, gollar we kwitansiýalar. Sandyk gutusyny we SDK goşuň - hyzmatdaşlar çalt, howpsuz we öňünden aýdyp boljak integrasiýa ederler we işewürlik hil we laýyklyk ýitirilmezden giňeldiler.