API экосистемалар

(Бөлүм: Экосистема жана тармак)

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

• Тез, алдын ала интеграция (time-to-integration ↓).
• Ишенимдүүлүк жана масштабдуулугу (SLO, QoS, backpressure).
• Коопсуздук жана жөнгө салуучу органдарды сактоо (минималдуу укуктар, аудит).
• Бузулуусуз эволюция (версиялар, шайкештик, фичефлагалар).

Принциптер: contract-first, маалыматтарды минималдаштыруу, демпотенттүүлүк, observability-by-default, "эки ылдамдыктагы" релиздер (core vs experimental).

2) API таксономиясы

1. REST/HTTP - синхрондуу CRUD/командалык иш, idempotency-key, pagination/cursors.
2. gRPC/QUIC - төмөн латенттүүлүк, агымдар, бинардык протоколдор.
3. Events (Pub/Sub) - домендик окуялар ('deposit.', 'payout.', 'bridge.', 'risk.').
4. Webhooks - кол тамгалар жана ретра менен кайтарым билдирүүлөр.
5. GraphQL (чектелген) - материалдаштырылган терезелердин үстүндөгү окууларды бириктирүү.
6. Admin/Meta - каталогдор, версиялар, статустар, ачкычтар, квоталар.

Кирүү деңгээли: Public (чектелген ыкмалар/окуу), Partner (сатып алуулар жана квоталар), Internal (жеке контурлар).

3) Келишимдер жана схемалар

OpenAPI/AsyncAPI/Protobuf IDL - чындыктын бир булагы.
Data Contracts - шайкештик тесттер, Линтер схемалар, "сынган" талааларды тыюу жок MAJOR.
Каталогдор: активдер/тармактар, PSP/ыкмалар, региондор/юрисдикциялар, SDK версиялары, мүмкүнчүлүктөрдүн желектери.

Минималдуу REST келишими (OpenAPI үзүндүсү)

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 }

Окуялар (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) Версия жана шайкештиги

SemVer: `MAJOR. MINOR. PATCH`. MINOR/PATCH - артка шайкеш; MAJOR - параллелдүү версиялар ('/v1 ', '/v2') + адаптерлер.
Deprecation саясат: терезе ≥ 90 күн, "эки линия" колдоо, келишимдер боюнча автоматтык билдирүүлөр.
Feature Flags: аймактар/өнөктөштөр боюнча талааларды/ыкмаларды киргизүү/өчүрүү.
Capability Negotiation: кол алышуу учурунда колдогон профилдерин жарыялоо.

5) Жол-жоболоштуруу, жол-жоболоштуруу жана курсорлор

Idempotency-Key үчүн командалар (create/cancel), TTL ачкычтары ≥ 72 саат.
Exactly-once семантика outbox/inbox жана idempotent консюмер аркылуу.
Пагинация курсор: 'next _ cursor', тиркемелерге/өчүрүүлөргө туруктуулук.
Сорттоо жана чыпкалар - туруктуу, так документтештирилген.

6) Коопсуздук жана ишеним

mTLS (service service), серттерди пиннинг жана ачкычтарды айлантуу.
OAuth2/OIDC (client credentials, кыскача TTL менен JWT), канал үчүн PoP/DPoP.
Webhook кол тамгалары (НМАС/ачкычтын версиясы/убактысы), кайталоодон коргоо.
RBAC/ABAC жана PoLP: сатып алуулар, org_id/tenant_id, объектке/операцияга лимиттер.
DLP/PII-минималдаштыруу: этикеткалар/логдор PII тыюу, ID tokenization.
Rate-limits жана WAF: per org/route/region, abuse коргоо.

Ачкыч саясатынын үлгүсү (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) Квоталар, QoS жана backpressure

QoS класстары: P0 (төлөмдөр/көпүрө/бүтүм), P1 (азык-түлүк), P2 (bulk/архив).
Квоталар/лимиттер: RPS, concur-requests, bytes/sec, окуя үчүн тема/партия.
Admission control: эрте четтөө "кымбат" суроо, оор-query-guard.
Backpressure: токендер/кредиттер, DLQ менен кезек, Jitter менен Retray.

Квота саясаты

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

8) байкоо: SLI/SLO, метрика, байкоо

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

SLO (көрсөтмөлөр): P0 p95 ≤ 400 ms, Availability ≥ 99. 95%; Webhook delivery p95 ≤ 2 с; Events freshness p95 ≤ 60 с.

Метрика: латенттүүлүк гистограммалары, ката коддору, жооп өлчөмү, RPS, per-tenant.
Traces: аркылуу 'trace _ id' (edge → gateway → service → DB → event/webhook).
Логи: структураланган, PII жок, 'request _ id' боюнча корреляция.

9) Даунтаймы жок релиздердин үлгүлөрү

Blue-Green/Canary SLO жана outlier-ejection менен.
Schema-биринчи эволюция: эски кардарлар үчүн гана талаа, адаптер кошуу.
Zero-downtime көчүрүү DD: онлайн DDL, эки тараптуу конвертерлер.
Өзгөрүүлөрдү көзөмөлдөө: timelock, аудит жана шайкештик реестри.

10) Каталогдор жана реестрлер

API/версиялар реестри

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)
);

Окуялар каталогу

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

Ачкычтар/сатып алуулар

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

11) Тестирлөө жана келишимдерге ылайык келүү

Contract-тесттер: кардарлардын генерациясы, схемаларды валидациялоо, negative-_cases.
Окуяларды кайталоо тесттери: кайталоого/кайра тартипке туруктуулук.
Chaos/Lat-тесттер: инъекция жоготуу/Jitter, жай Stop.
Security-tests: Webhook кол, ачкычтарды айлантуу, кайталоо кол.
Performance профилдери: SLA спайктар, "ысык" маршруттар, ДА/көпүрө көз карандылык.

12) Interface мисалдар

Webhooks (кол жана retrailer)

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 (топтоо окуу, бир гана окуу)

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

gRPC (окуялардын агымы)

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

13) Процесстер жана ролдор

API Owner - келишим/версия/SLO/квота.
Коопсуздук - ачкычтар/кол тамгалар/аудит/DLP.
SRE/Ops - дашборддор, алерталар, capacity.
Partner Success - онбординг, лимиттер, физикалык фонддор.
Compliance - юрисдикциялар, санкциялар, отчеттуулук.

14) Дашборд

Core API: latency/error/RPS маршруттар жана тентанттар боюнча.
Webhooks: delivery p95, retries, drops, кол тамгалар.
Events: freshness, lag, consumer health, DLQ.
Security: мөөнөтү бүткөн ачкычтар, кол тамгалар, баш тарткан суроолор.
Governance: активдүү версиялары/депрекейттери, келишимдердин шайкештиги.

15) Playbook окуялар

A. P95 латенттүүлүк өсүшү P0

1. P0 жана P2-throttle артыкчылыгын киргизүү; 2) шлюздарды масштабдоо;

2. окуулардын бир бөлүгүн кэшке которуу; 4) "ысык" маршруттарды талдоо.

B. Down delivery webhook

1. Колдорду/саат жылыштарын текшерүү, 2) retrais/таймауттарды көбөйтүү,

2. 4) убактылуу пулл-эндпоинтке өтүү.

C. drift келишимдер

1. "strict mode" күйгүзүү (туура эмес билдирүүлөрдү кесип),

2. өндүрүүчүгө кабарлоо, 3) адаптер бошотуу, 4) пост-мортем, линтерлерди жаңыртуу.

D. Ачкычтын/серттин компромисстери

1. Revoke/rotate, 2) Webhuke кайра, 3) аудит, 4) өнөктөштөрдү билдирүүгө.

E. кайталоо/дубль жарылуу

1. Idempotency-Key/TTL текшерүү, 2) дедуп күчөтүү, 3) "ызы-чуу" булагы чектөө.

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

1. Контракттарды сүрөттөө (OpenAPI/AsyncAPI/IDL), линтерлерди жана CI.
2. Орнотуу auth (OAuth2/OIDC, mTLS), кол тамгалар, ачкычтарды айлантуу.
3. Квоталарды/QoS/лимиттерди, оор-query-guard жана backpressure киргизүү.
4. байкоо жогорулатуу: SLI/SLO, жолдор, дашборддор, алерталар.
5. Releases уюштуруу: canary/көк-жашыл, shema-биринчи миграция.
6. Версиялар/окуялар/ачкычтар каталогун жана депрекейт процесстерин ишке киргизүү.
7. Chaos/perf/security-тесттерди өткөрүү, playbook уюштуруу.
8. Маалыматтарды минималдаштырууну жана жөнгө салуучу органдарга шайкештигин такай ревизиялоо.

17) Глоссарий

Contract-first - кодго чейин расмий келишимдер аркылуу API долбоорлоо.
Idempotency-Key - операциянын кайталанышын коопсуз кылган ачкыч.
AsyncAPI - окуя интерфейстеринин спецификациясы.
QoS - тейлөө сапаты/артыкчылыктуу класс.
DLQ - көйгөйлүү билдирүүлөр үчүн "өлүк кезек".
Error budget burn - SLO карата "өрттөө" бюджетинин ката ылдамдыгы.

Жыйынтык: Экосистеманын APIсы - бул эндпоинттердин жыйындысы эмес, контракттардын, коопсуздуктун, квоталардын жана байкоонун башкарылуучу системасы. Бул алкакты ээрчип, экосистема тез интеграцияны, алдын ала айтылган SLO жана коопсуз эволюцияны алып жатат - тармактык деңгээлден жана аутентификациядан окуя агымына жана отчеттуулукка чейин.