API интерфейсі арқылы операциялар

(Бөлім: Операциялар және Басқару)

1) Мақсаты және қағидаттары

API - бұл экожүйенің «операциялық қабаты»: келісімшарт арқылы автоматтандырылмағандардың бәрі қолмен жұмыс істеуге және тәуекелдерге айналады.

• Contract-first: алдымен ерекшелік (OpenAPI/JSON Schema/AsyncAPI), содан кейін іске асыру.
• Secure-by-default: ең аз сатып алулар, қысқа TTL, мьютуал-TLS/қолтаңбалар.
• Observable: end-to-end трассировкасы және SLA метрикасы.
• Idempotent: қайталау қауіпсіз.
• Backwards-compatible: «бұзатын» өзгерістерсіз эволюция.
• Auditable: криптографиялық расталған фактілер (түбіртектер).

2) Келісімшарт және модельдер (референс)

sync сұраулары үшін OpenAPI; Оқиғалар/вебхуктар үшін 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.
Сатып алулар/ресурстық рөлдер: 'payments. write`, `catalog. read`, `audit. export`.
ReBAC: «иелену бойынша» қолжетімділік (тенант/аккаунт/саб-аккаунт).
JIT-құпиялар: қысқа мерзімді токендер, құрылғыға/кіші желіге/аймаққа байланыстыру.
Күрделі операциялар үшін Device posture & mTLS (төлемдер, кілттер).

4) Теңсіздік және «біркелкі»

Idempotency-Key (тақырып) + '(key, account, route)' бойынша дедуп TTL-терезесінде.
Оқиғаларды жариялау үшін Outbox/CDC - кепілді жеткізу.
Exactly-once-effects: жанама әсерлер транзакциялық журнал арқылы тіркеледі; қайталау сол «түбіртекке» ('receipt _ hash') әкеледі.
Retry-саясат: экспоненциалды бэк-офф, джиттер, ең үлкен терезелер.

5) Лимиттер, квоталар, басымдықтар

Rate limits: per-key/tenant/route/region; «жұмсақ» (429) және «қатты» (үзік).
Квоталар/бюджеттер: айлық/тәуліктік каптар, вебхактар 'QuotaCapReached'.
Fair-use: сервистік деңгей бойынша тенанттардың басымдығы (Gold/Silver/Bronze).
Burst-буферлер: көршілердің тозуынсыз қысқа жарылыстар.

6) Пагинация, сүзгілер, іріктемелер

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.
Журнал/транзакциялар үшін Time-sliced ('from', 'to', 'watermark').
Filtering DSL: whitelisted поля, `?status=...&tenant=...&region=...`.
Consistency hints: 'snapshot _ at '/' as _ of' үшін репортингтік API.

7) Нұсқалау және үйлесімділік

SemVer: `v1`, `v1. 1 '(кеңейтулер),' v2 '- тек жаңа жолдар/неймспейстер бойынша.
Эволюция ережелері: тек өрістерді/мәндерді қосу, терезе арқылы «deprecate → remove».
Compatibility tests: «келісімшарттар-қалай-тесттер» (consumer-driven).

8) Оқиғалар, вебхактар және түбіртектер

AsyncAPI/payload/қолтаңбалардың тақырыптарын сипаттайды.
Қолы: HMAC/EdDSA, «X-Signature», «X-Nonce», «X-Timestamp» тақырыптары (тар терезе).
Түбіртектер (receipts): 'receipt _ hash' және сыни оқиғалардағы DSSE-қолтаңба (төлемдер, RTP/лимиттердің өзгеруі, прайс-парақтар).
Ретраи және дедуп: 'idempotency _ key '/' event _ id' бойынша сәйкестігі.
DLQ/карантин: себептері бар салидті емес/қайталама хабарламалар.

9) Бақылау және сапа

Traces: міндетті 'trace _ id/span _ id' шлюз/бизнес оқиғалар/вебхактар арқылы.
Metrics: қол жетімділік, p50/p95/p99, error-rate, retry-rate, cost per 1k.
Logs: құрылымдалған, құпиясыз/PII; 'tenant/region/version' белгілері.
SLO/алерта: SLO-бағытталған шарттар және авто-рандар (pause/re-route/rollback).

10) Қателер және мәртебе семантикасы

2xx - табыс (асинхронды операциялар үшін 202).
4xx - клиенттің кінәсі (422 - валидация, 409 - жанжал/демпотенттілік, 429 - лимиттер).
5xx - уақытша проблемалар.
Қате денесі: 'code', 'message', 'trace _ id', 'hint', 'retry _ after?'.
Серіктестер үшін UX: әрбір қатеге «не істеу керек» кестесі.

11) Код сияқты саясат (OPA/ABAC)

Орталықтандырылған авторизация: «кім/не/қайда/қашан/не үшін».
Git саясаты, код-ревю, CI-тесттер (pre-flight: "саясат рұқсат ете ме? »).
SoD-чек: «төлем жасау» ≠ «бекiту».

12) Қауіпсіздік, құпиялылық, комплаенс

PII-минимизация: токенизация/маскалар, тек қана мақұлданған джобтар арқылы бастапқы жүйеге қол жеткізу.
Құпиялар: Vault/KMS, қысқа TTL, ротациялар; shared-құпияларға тыйым салу.
Шифрлау: mTLS/TLS 1. 3, AES-GCM at-rest, HSTS/PKP орынды.
Jurisdiction-aware: деректерді/кілттерді per region.
Аудит журналдары: WORM, Merkle-срез, DSSE-қолтаңбалар.

13) Пайдалану: SLI/SLO және дашбордтар

• per-route/region қол жетімділігі.
• Жасырындылық p95 (read/write).
• Вебхуктардың (түбіртектердің) табыстылығы, жеткізу мерзімі.
• Error-rate/Retry-rate.
• Cost per 1k сұрау және egress.

SLO (мысал): 99. 95% қол жетімділік; p95 ≤ 120/250 мс; вебхактар ≥ 99. 5 %/5-мин; P1 MTTR ≤ 60 мин.

14) Өзгерістерді басқару (релиздер/кері қайтулар)

шлюздер мен сындарлы бағыттар үшін Blue-Green/Canary.
Шығарылмайтын мінез-құлыққа арналған фичефлагтар.
Схемалар мен payload үшін Expand → Migrate → Contract.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
Артефактілер: қол қойылған бейнелер/манифесттер, нұсқалар тізілімі.

15) SDK, клиенттер, «құмсалғыштар»

Қателер мен ретрайлардың бірдей семантикасы бар ресми SDK (TS/Java/Python/Go).
Тест кілттері/сертификаттары және PSP/KYC/контент провайдерлері бар Sandbox-орта.
Contract-tests SDK CI, nightly-үйлесімділігіне енгізілген.

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/лимиттер: Gold үшін қақпақты көтеру, «шулы» кілттердің троттлингі, серіктеспен байланыс.
WebhookLag: воркерлерді/батчтерді үлкейту, кезектерге басымдық беру, міндетті емес вебхоктарды уақытша өшіру.
PriceMismatch (catalog/FX/Tax): нұсқаларды салыстыру, кэштің форс-мүгедектігі, артефактіні қайтару, өтемақы.
PSP Outage: бағытты ауыстырып қосу, «сұр» транзакциялар, репликалар карантині.
Compromise API-key: дереу қайтарып алу, ротация, соңғы 30 күннің аудиті.

20) iGaming/финтех ерекшелігі

RTP/Limits API: тек агрегаттар және профильдер нұсқалары; өзгерістер - түбіртектермен.
Төлемдер/төлемдер: 202 + қолдары бар вебхактар; тапсырыстың кілтіне сәйкестігі.
Аффилиаттар: конверсиялар дедуп, дауларға арналған эскроу, қол қойылған есептер.
Жауапты ойын: лимиттер мен RG оқиғалары үшін «guardrails API» көрмесін.

21) Енгізу чек-парағы

• Келісімшарт сипатталған (OpenAPI/AsyncAPI), CI-валидация және consumer-tests.
• Сыни бағыттар үшін OAuth2/OIDC, сатып алулар, JIT-құпиялар және mTLS теңшелген.
• Іспеттестік, ретра, DLQ және карантин енгізілді.
• Қақпалар бойынша лимиттер/квоталар/басымдықтар мен тәуекелдер.
• Курсорлармен пагинация, консистенттік іріктемелер 'as _ of'.
• Нұсқалау және Deprecation-саясат.
• Қолтаңбалары/түбіртектері, репликалары және дедупі бар вебхактар.
• Трассировка/метрика/логи, SLO және руна.
• WORM журналдары, DSSE қолтаңбалары, Merkle бөліктері.
• SDK, sandbox, симуляторлар, код мысалдары және «how-to».

22) FAQ

Неге 202 ұзақ операциялар үшін?
Қосылымды ұстамау және вебхук арқылы сенімді ретрай/түбіртекті қамтамасыз ету үшін.

Екі: OpenAPI және AsyncAPI қажет пе?
Иә: командалар/сұраулар үшін sync, оқиғалар/күй келісімі үшін async.

Бұзатын өзгерістерді қалай болдырмау керек?
«Тек қосу» ережесі, deprecate → observe → remove, клиенттердің келісімшарт-тестілері.

Түбіртектерді қайда сақтау керек?
WORM-аймағында қолтаңбалармен; 'receipt _ hash' клиентке қайтарылады және сұрау бойынша салыстырылады.

Резюме: API арқылы операциялар - бұл келісімшарт пен пайдалану тәртібі: қол жеткізудің қатаң моделі және теңсіздік, лимиттер мен нұсқалар, бақылау және SLO, қолтаңбалар мен түбіртектер. Құмсалғыштарды және SDK қосыңыз - серіктестер тез, қауіпсіз және болжамды интеграцияланады, ал бизнес - сапа мен комплаенсті жоғалтпастан масштабталады.