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) Патерни релізів без даунтайму

Blue-Green/Canary з SLO-гейтами і outlier-ejection.
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.
Replay-тести подій: стійкість до повторів/перевпорядкування.
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 і безпечну еволюцію без даунтайму - від мережевого рівня і автентифікації до подієвих потоків і звітності.