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 policy: терезе ≥ 90 күн, «екі желі» қолдау, келісімшарттар бойынша автоматты хабарламалар.
Feature Flags: өңірлер/серіктестер бойынша өрістерді/әдістерді қосу/ажырату.
Capability Negotiation: қол алысу кезінде қолдау көрсетілетін профильдерді жариялау.

5) Теңсіздік, тәртіптер мен курсорлар

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

6) Қауіпсіздік және сенім

mTLS (service service), серттердің пиннингі және кілттердің ротациясы.
Арнаға байланыстыруға арналған OAuth2/OIDC (client credentials, JWT қысқаша TTL), PoP/DPoP.
Webhook қолтаңбалары (НМАС/кілттің нұсқасы/уақыты), қайталанудан қорғау.
RBAC/ABAC және PoLP: сатып алулар, org_id/tenant_id, объектіге/операцияға лимиттер.
DLP/PII-минимизация: лейблдерде/логтарда PII тыйым салу, идентификаторларды токенизациялау.
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: «қымбат» сұраулардың ерте ауытқуы, heavy-query-guard.
Backpressure: токендер/кредиттер, DLQ кезектері, джиттермен ретрайлер.

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

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 мс, Availability ≥ 99. 95%; Webhook delivery p95 ≤ 2 с; Events freshness p95 ≤ 60 с.

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

9) Даунтайсыз релиздер паттерндері

SLO-гейт және outlier-ejection бар Blue-Green/Canary.
Schema-first эволюциясы: тек өрістерді қосу, ескі клиенттер үшін адаптерлер.
Zero-downtime көші-қон БД: онлайн-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-tests: клиенттерді генерациялау, схемаларды валидациялау, negative-_cases.
Оқиғалар сынақтары: қайталауға/қайта реттеуге төзімділік.
Chaos/Lat-tests: жоғалту/джиттер инъекциялары, баяу стор.
Security-tests: вебхук қолтаңбалары, кілттерді ротациялау, қайталау шабуылдары.
Performance-профильдер: SLA-дәнекерлеу, «ыстық» бағыттар, DA/тәуелділік көпірі.

12) Интерфейстердің мысалдары

Webhooks (қолтаңбасы мен ретрайлері)

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/квота.
Security - кілттер/қолтаңбалар/аудит/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. delivery webhook құлдырауы

1. Қолтаңбаларды/сағаттық ауысуды тексеру; 2) Ретраяларды/таймауттарды ұлғайту

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

C. drift келісімшарттары

1. 'strict mode' дегенді қосу

2. 3) адаптер шығару, 4) пост-мортем, линтерлерді жаңарту.

D. Кілт/серт компрометациясы

1. Revoke/rotate; 2) вебхоктарды қайта түсіру; 3) аудит; 4) серіктестерді хабардар ету.

E. Қайталау/қайталау жарылысы

1. Idempotency-Key/TTL тексеру; 2) дедупты күшейту; 3) «шулы» көзді шектеу.

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

1. Келісімшарттарды сипаттау (OpenAPI/AsyncAPI/IDL), линтерлер мен CI қосу.
2. auth (OAuth2/OIDC, mTLS), вебхук қолтаңбаларын, кілттердің айналымын баптау.
3. / QoS/лимиттерін, heavy-query-guard және backpressure енгізу.
4. Бақылауды жоғарылату: SLI/SLO, трассалар, дашбордтар, алерта.
5. Релиздерді ұйымдастыру: canary/blue-green, schema-first көші-қон.
6. Нұсқалар/оқиғалар/кілттер каталогын және депрекейт процестерін іске қосу.
7. Chaos/perf/security-тесттер өткізу, плейбуктерді рәсімдеу.
8. Деректерді барынша азайту және реттеуішке сәйкестігін үнемі ревизиялау.

17) Глоссарий

Contract-first - кодқа дейін формалды келісімшарттар арқылы API жобалау.
Idempotency-Key - әрекетті қайталауды қауіпсіз ететін кілт.
AsyncAPI - оқиғалық интерфейстердің ерекшелігі.
QoS - қызмет көрсету сапасы/басымдылығы сыныбы.
DLQ - проблемалық хабарлар үшін «өлі кезек».
Error budget burn - SLO-ға қатысты қателерді бюджетті «жағу» жылдамдығы.

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