API интерфейси аркылуу иш

(Бөлүк: Операциялар жана башкаруу)

1) Максаты жана принциптери

API экосистеманын "операциялык катмары" болуп саналат: келишим аркылуу автоматтандырылбаган нерселердин баары кол менен иштөөгө жана тобокелдиктерге айланат.

• Contract-first: биринчи өзгөчөлүгү (OpenAPI/JSON схемасы/AsyncAPI), андан кийин ишке ашыруу.
• Secure-by-default: минималдуу сатып алуулар, кыска TTL, мьютуал-TLS/кол тамгалар.
• Observable: end-to-end tracking жана 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-Secrets: кыскача токендер, түзмөк/көмөкчордондор/аймакты байлап.
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: кызмат денгээлде (Алтын/Күмүш/Bronze) боюнча тенанттардын артыкчылыгы.
Бурст буферлер: кошуналардын деградациясы жок кыска жарылуулар.

6) Pagination, чыпкалар, үлгүлөрү

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) Окуялар, Webhook жана дүмүрчөктөр

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' аркылуу шлюз/бизнес-окуялар/webhucks.
Metrics: жеткиликтүүлүк, p50/p95/p99, error-rate, retry-rate, cost per 1k.
Logs: структураланган, эч кандай жашыруун/PII; tags 'tenant/region/version'.
SLO/Алерт: SLO-багытталган шарттар жана auto-run (пауза/re-route/rollback).

10) Каталар жана статустардын семантикасы

2xx - ийгилик (202 асинхрондук операциялар үчүн).
4xx - кардардын күнөөсү (422 - валидация, 409 - конфликт/демпотенттүүлүк, 429 - лимиттер).
5xx - убактылуу көйгөйлөр.
ката орган: 'code', 'message', 'trace _ id', 'hint', 'retry _ after?'.
өнөктөштөр үчүн UX: таблица "эмне кылуу керек" ар бир ката.

11) Саясат-Code (OPA/ABAC)

Борборлоштурулган авторизация: "ким/эмне/кайда/качан/эмне үчүн".
Саясат Git, Code Review, CI-тесттер (pre-flight: "саясат жол береби? »).
SoD-чек: "төлөм түзүү" ≠ "бекитүү".

12) Коопсуздук, купуялык, комплаенс

PII-минималдаштыруу: Токендештирүү/маскалар, биринчиликке жетүү гана бекитилген джобдор аркылуу.
Secrets: 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/аймак.
• Жашыруун p95 (read/write).
• Вебхуктардын ийгилиги (дүмүрчөктөр), жеткирүү мөөнөтү.
• Error-rate/Retry-rate.
• Cost per 1k суроолор жана egress.

SLO (мисал): 99. 95% жеткиликтүүлүгү; p95 ≤ 120/250 мс; Webhuke ≥ 99. 5 %/5-мин; P1 MTTR ≤ 60 мин.

14) Өзгөрүүлөрдү башкаруу (релиздер/артка кайтаруулар)

Blue-Green/Canary үчүн кулпулар жана маанилүү маршруттар.
Ficheflagy чыгаруу жок жүрүм-турум үчүн.
Expand → Migrate → Contract үчүн схемалар жана payload.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
Артефакттар: кол коюлган сүрөттөр/манифесттер, версиялардын реестри.

15) SDK, кардарлар, "Sandbox"

Расмий SDK (TS/Java/Python/Go) каталар жана retrains бирдей семантикасы менен.
Сыноо ачкычтары/күбөлүктөрү жана PSP/KYC/мазмун провайдерлери менен Sandbox чөйрөсү.
Contract-тесттер SDK CI, түнкү шайкештиги киргизилген.

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) Сапат Metrics

Contract Drift: 0 "бузуучу" өзгөрүүлөр жок депрекейт.
Idempotency Error Rate: ≤ 0. 01%.
Webhook Success: ≥ 99. 5%, лаг p95 ≤ 60 б.
Auth Fail vs Abuse: зыяндуу блоктордун үлүшү, ызы-чуу ≤ максаттуу деңгээл.
Cost/1k: маршруттар жана региондор боюнча көзөмөл (бюджеттер/кап-алерталар).
SDK Adoption: расмий SDK аркылуу жол үлүшү.

19) Playbook окуялар

Spike 429/лимиттери: Gold үчүн Cap жогорулатуу, Trottling "ызы-чуу" ачкычтар, өнөктөш менен байланыш.
WebhookLag: Workers/Batches жогорулатуу, кезек артыкчылык, убактылуу кошумча Webhook өчүрүү.
PriceMismatch (catalog/FX/Tax): версияларды салыштыруу, кэшти форс-майыптандыруу, артефактты артка кайтаруу, компенсация.
PSP Outage: которуу маршруту, карантин "боз" бүтүмдөр, сөз.
Compromise API-key: дароо кайра чакыртып алуу, ротация, акыркы 30 күндүк аудит.

20) iGaming/Fintech өзгөчөлүктөрү

RTP/Limits API: гана агрегаттар жана профилдер нускасы; өзгөртүүлөр - квитанциялар менен.
Төлөмдөр/төлөмдөр: 202 + кол тамгалар менен вебхактар; буйруктун ачкычына демпотенттик.
Аффилиаттар: конверсия дедуп, талаш-тартыштар үчүн эскроу, кол коюлган отчеттор.
Жооптуу оюн: чектер жана RG-окуялар үчүн "guardrails API" көргөзмөгө.

21) Киргизүү чек-тизмеси

• баяндалган келишим (OpenAPI/AsyncAPI), CI-валидация жана consumer-tests.
• Customized OAuth2/OIDC, сатып алуулар, JIT-сырлар жана mTLS үчүн маанилүү маршруттар.
• Idempotentity, Retray, DLQ жана карантин киргизилген.
• Лимиттер/квоталар/артыкчылыктар жана капка боюнча тобокелдиктер.
• Pagination курсор, консистенттик үлгүлөрү 'as _ of'.
• Version & Deprecation-саясат.
• Кол тамгалар/дүмүрчөктөр, репликалар жана дедуп менен Webhook.
• Tracking/Metrics/Logi, SLO жана Runes.
• WORM-журналдар, DSSE-кол тамгалар, Merkle-тилкелер.
• SDK, sandbox, симуляторлор, коддун мисалдары жана "how-to".

22) FAQ

Эмне үчүн 202 узак иш үчүн?
байланышты кармап жана Webhook аркылуу ишенимдүү retrai/дүмүрчөк камсыз кылуу үчүн эмес.

Эки: OpenAPI жана AsyncAPI керек?
Ооба: командалар/суроолор үчүн sync, окуялар/шарттар боюнча async.

Кантип бузуучу өзгөрүүлөрдү болтурбоо керек?
Эреже "гана кошуу", deprecate → observe → remove, кардарларды келишим-тесттер.

Дүмүрчөктөрдү кайда сактоо керек?
WORM зонасында кол тамгалар менен; 'receipt _ hash' кардарга кайтарылып берилет жана суроо-талап боюнча текшерилет.

Резюме: API аркылуу операциялар - бул келишимдин жана эксплуатациянын дисциплинасы: катуу кирүү жана демпотенттик модели, лимиттер жана версиялар, байкоо жана SLO, кол тамгалар жана квитанциялар. Sandbox жана SDK кошуу - жана өнөктөштөр тез, коопсуз жана алдын ала интеграцияланат, ал эми бизнес сапатын жана комплаенс жоготуусуз масштабдалат.