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 (HMAC/версия ключа/время), защита от повторов.
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 и безопасную эволюцию без даунтайма — от сетевого уровня и аутентификации до событийных потоков и отчетности.