Ekotizim API

(Bo’lim: Ekotizim va Tarmoq)

1) Maqsad va prinsiplar

• Tezkor, oldindan aytib bo’ladigan integratsiyalar (time-to-integration ↓).
• Ishonchlilik va masshtablanish (SLO, QoS, backpressure).
• Xavfsizlik va tartibga solish qoidalariga rioya qilish (minimal huquqlar, audit).
• Buzilishsiz evolyutsiya (versiyalar, muvofiqlik, fizeflaglar).

Prinsiplari: contract-first, ma’lumotlarni minimallashtirish, idempotentlik, observability-by-default, relizlarning «ikki tezligi» (core vs experimental).

2) API taksonomiyasi

1. REST/HTTP - sinxron CRUD/buyruqlar, idempotency-key, pagination/cursors.
2. gRPC/QUIC - past latentlik, oqimlar, binar protokollar.
3. Events (Pub/Sub) - domen hodisalari (’deposit.’,’payout.’,’bridge.’,’risk.’).
4. Webhooks - imzolar va retrajlar bilan qaytish xabarnomalari.
5. GraphQL (cheklangan) - materiallashtirilgan vitrinalar ustiga o’qishni yig’ish.
6. Admin/Meta - kataloglar, versiyalar, maqomlar, kalitlar, kvotalar.

Kirish darajalari: Public (cheklangan usullar/oʻqish), Partner (sotib olish va kvotalar), Internal (shaxsiy konturlar).

3) Kontraktlar va sxemalar

OpenAPI/AsyncAPI/Protobuf IDL - haqiqatning yagona manbai.
Data Contracts - moslik testlari, sxema linterlari, MAJORsiz «buzuvchi» maydonlarni taqiqlash.
Kataloglar: aktivlar/tarmoqlar, PSP/usullar, hududlar/yurisdiksiyalar, SDK versiyalari, imkoniyatlar bayroqlari.

Minimal REST-kontrakt (OpenAPI fragmenti)

yaml openapi: 3. 0. 3 info: { title: Ecosystem Core API, version: "2. 6. 0" }
paths:
/v2/payouts:
post:
operationId: createPayout parameters:
- in: header name: Idempotency-Key required: true schema: { type: string, maxLength: 64 }
requestBody:
required: true content:
application/json:
schema:
$ref: "#/components/schemas/PayoutRequest"
responses:
"202": { $ref: "#/components/responses/Ack" }
"409": { description: "Duplicate (idempotent)" }
components:
schemas:
PayoutRequest:
type: object required: [amount, currency, destination]
properties:
amount:  { type: string, pattern: "^[0-9]+(\\.[0-9]{1,9})?$" }
currency: { type: string, example: "USD" }
destination: { type: string }
metadata: { type: object, additionalProperties: true }

Voqealar (AsyncAPI)

yaml asyncapi: 2. 6. 0 info: { title: Ecosystem Events, version: "1. 9. 0" }
channels:
payout. finalized:
subscribe:
message:
name: PayoutFinalized payload:
type: object required: [id, ts, amount, currency, status, signature]
properties:
id: { type: string }
ts: { type: string, format: date-time }
amount: { type: string }
currency: { type: string }
status: { type: string, enum: ["finalized","failed"] }
signature: {type: string} # source signature

4) Versiyalash va muvofiqlik

SemVer: `MAJOR. MINOR. PATCH`. MINOR/PATCH - orqaga mos; MAJOR - parallel versiyalar (’/v1’, ’/v2’) + adapterlar.
Deprecation policy: deraza ≥ 90 kun, «ikki yo’nalish» qo’llab-quvvatlash, kontraktlar bo’yicha avtomatik bildirishnomalar.
Feature Flags: mintaqalar/hamkorlar boʻyicha maydonlarni/usullarni yoqish/oʻchirish.
Capability Negotiation: qo’l siqishda qo’llab-quvvatlanadigan profillarni e’lon qilish.

5) Idempotentlik, tartib va kursorlar

Idempotency-Key uchun (create/cancel), TTL kalitlari ≥ 72 soat.
Exactly-once semantika outbox/inbox va idempotent konsumer orqali.
’next _ cursor’ kursorlari bilan paginatsiya qilish, qoʻyish/olib tashlashga chidamlilik.
Saralash va filtrlar barqaror, aniq hujjatlashtirilgan.

6) Xavfsizlik va ishonch

mTLS (service service), sertlarning pinning va kalitlarning rotatsiyasi.
Kanalga ulanish uchun OAuth2/OIDC (client credentials, JWT, qisqacha TTL), PoP/DPoP.
Webhook imzolari (NMAS/kalit/vaqt versiyasi), takrorlashlardan himoya qilish.
RBAC/ABAC va PoLP: obyekt/operatsiya uchun xaridlar, org_id/tenant_id, limitlar.
DLP/PII-minimallashtirish: yorliqlar/loglarda PII taqiqlash, identifikatorlarni tokenlashtirish.
Rate-limits va WAF: per org/route/region, abuse himoyasi.

Kalit siyosati namunasi (YAML)

yaml auth:
oauth2:
issuer: "https://auth. ecosys"
jwks_uri: "https://auth. ecosys/.well-known/jwks. json"
token_ttl_s: 900 mtls:
required_for: ["internal","partner_p0"]
scopes:
- name: payouts:write
- name: payouts:read
- name: events:subscribe

7) Kvotalar, QoS va backpressure

QoS klasslari: P0 (to’lovlar/ko’prik/yakuniy), P1 (oziq-ovqat), P2 (bulk/arxiv).
Kvotalar/limitlar: RPS, concur-requests, bytes/sec, mavzu/voqealar uchun partiya.
Admission control: «qimmat» soʻrovlarni erta rad etish, heavy-query-guard.
Backpressure: tokenlar/kreditlar, DLQ bilan navbatlar, jitter bilan retraylar.

Kvotalar siyosati

yaml quotas:
partner_default:
rps: 200 concurrent: 100 webhooks_outbound_rps: 50 p0:
rps: 100 p95_latency_ms: 400

8) Kuzatish darajasi: SLI/SLO, metrika, trastirovka

• p95/99 latency по маршрутам, Success Rate, Error budget burn, Queue-lag p95, Freshness webhooks, Delivery success%.
• Contract Compliance% (sxemalar/imzolar).
• Webhook retry/dropped%.

SLO (taxminlar): P0 p95 ≤ 400 ms, Availability ≥ 99. 95%; Webhook delivery p95 ≤ 2 с; Events freshness p95 ≤ 60 с.

Metriklar: latentlik gistogrammalari, xato kodlari, javoblar hajmi, RPS, per-tenant.
Treyslar:’trace _ id’orqali (edge → gateway → service → DB → event/webhook).
Loglar: strukturalangan, PIIsiz,’request _ id’bilan bog’langan.

9) Pastki taymsiz relizlar patternlari

SLO-geytlar va outlier-ejection bilan Blue-Green/Canary.
Schema-first evolyutsiyasi: faqat eski mijozlar uchun maydonlarni, adapterlarni qoʻshish.
Zero-downtime migratsiya DD: onlayn-DDL, ikki yo’nalishli konvertorlar.
Oʻzgarishlarni nazorat qilish: timelock, audit va muvofiqlik reyestri.

10) Kataloglar va reyestrlar

API/versiyalar reyestri

sql
CREATE TABLE api_registry(
name TEXT, kind TEXT,      -- rest    grpc    events    webhook version TEXT, status TEXT,   -- active    canary    deprecated    retired slo JSONB, owner TEXT,
PRIMARY KEY (name, version)
);

Voqealar katalogi

sql
CREATE TABLE event_catalog(
topic TEXT PRIMARY KEY,
schema_version TEXT,
qos TEXT,
retention_days INT,
pii BOOLEAN DEFAULT false
);

Kalitlar/skoplar

sql
CREATE TABLE api_keys(
key_id TEXT PRIMARY KEY,
org_id TEXT, scopes TEXT[], status TEXT, expires_at TIMESTAMPTZ
);

11) Test sinovlari va kontraktlarga muvofiqlik

Contract-tests: mijozlarni ishlab chiqarish, sxemalarni validatsiya qilish, negative-_cases.
Voqealar replay-testlari: takrorlashga/qayta tartibga solishga chidamlilik.
Chaos/Lat-tests: yo’qotish/jitter in’ektsiyalari, sekin stor.
Security-tests: vebxuk imzolari, kalitlarning rotatsiyasi, takrorlash hujumlari.
Performance-profillar: SLA-paykalar, «issiq» yo’nalishlar, DA/qaramlik ko’prigi.

12) Interfeys namunalari

Webhooks (imzo va retralar)

yaml webhooks:
deliveries:
retry:
attempts: 5 backoff_ms: [200, 800, 1600, 3200, 6400]
jitter: true signature:
alg: "HMAC-SHA256"
header: "X-ECO-Signature"
timestamp_header: "X-ECO-Timestamp"
tolerance_s: 300

GraphQL (faqat oʻqish)

graphql type Query {
payouts(status: [Status!], first: Int!, after: String): PayoutConnection!
}

gRPC (voqealar oqimi)

proto service EventStream {
rpc Subscribe(SubscribeRequest) returns (stream Event);
}

13) Jarayonlar va rollar

API Owner - kontrakt/versiya/SLO/kvotalar.
Security - kalitlar/imzolar/audit/DLP.
SRE/Ops - dashbordlar, alertlar, capacity.
Partner Success - onbording, limitlar, fitnalar.
Compliance - yurisdiksiyalar, sanksiyalar, hisobotlar.

14) Dashbordlar

Core API: latency/error/RPS yo’nalishlar va tentantlar bo’yicha.
Webhooks: delivery p95, retries, drops, imzolar.
Events: freshness, lag, consumer health, DLQ.
Security: tugash kalitlari, imzolar, rad etilgan soʻrovlar.
Governance: faol versiyalar/deprekeytlar, kontraktlarning muvofiqligi.

15) Hodisalar Playbook

A. Latentlikning p95 o’sishi P0

1. P0 va P2-throttle ustuvorligini kiritish; 2) shlyuzlarni ko’paytirish;

2. oʻqishning bir qismini keshga oʻtkazish; 4) «issiq» yo’nalishlarni tahlil qilish.

B. Qulash delivery webhook

1. Imzolarni/soatlik siljishni tekshirish, 2) retrai/taymautlarni kattalashtirish,

2. 4) pull-endpointga vaqtincha o’tish.

S. Drift kontraktlari

1. «strict mode» ni yoqish (notoʻgʻri xabarlarni kesish),

2. prodyuserni xabardor qilish; 3) adapterni chiqarish; 4) post-mortem, linterlarni yangilash.

D. Kalit/sert kompromsatsiyasi

1. Revoke/rotate, 2) vebxuklarni qayta sinab ko’rish, 3) audit, 4) sheriklarni xabardor qilish.

E. takrorlash/dubllar portlashi

1. Idempotency-Key/TTL ni tekshirish, 2) dedupni kuchaytirish, 3) «shovqinli» manbani cheklash.

16) Joriy etish chek-varaqasi

1. Shartnomalarni tavsiflash (OpenAPI/AsyncAPI/IDL), linterlarni va CIni yoqish.
2. Auth (OAuth2/OIDC, mTLS), vebxuk imzolari, kalitlar rotatsiyasini moslash.
3. Kvotalar/QoS/limitlar, heavy-query-guard va backpressure.
4. Kuzatishni oshirish: SLI/SLO, trassalar, dashbordlar, alertlar.
5. Quyidagi relizlarni tashkil etish: canary/blue-green, schema-first migratsiya.
6. Versiyalar/hodisalar/kalitlar katalogini va deprekeyt jarayonlarini ishga tushirish.
7. Chaos/perf/security-testlar o’tkazish, pleybuklarni rasmiylashtirish.
8. Ma’lumotlarni minimallashtirish va tartibga solish qoidalariga muvofiqligini muntazam ravishda revizsiya qilib borsin.

17) Glossariy

Contract-first - kodgacha bo’lgan rasmiy kontraktlar orqali APIni loyihalashtirish.
Idempotency-Key - operatsiyaning takrorlanishini xavfsiz qiladigan kalit.
AsyncAPI - voqea interfeyslarining tavsifi.
QoS - xizmat ko’rsatish sifati/ustuvorlik darajasi.
DLQ - muammoli xabarlar uchun «o’lik navbat».
Error budget burn - SLOga nisbatan xatolarni «yoqish» tezligi.

Xulosa: ekotizimning API - bu endpointlar to’plami emas, balki kontraktlar, xavfsizlik, kvotalar va kuzatuvlarning boshqariladigan tizimi. Ushbu freymvordan so’ng, ekotizim tezkor integratsiyalashuvlarga, oldindan aytib bo’ladigan SLO va xavfsiz evolyutsiyaga ega bo’ladi - tarmoq darajasi va autentifikatsiyadan tortib, hodisa oqimi va hisobotlargacha.