Справочник Streaming API

Streaming API — это обычный HTTP-интерфейс для публикации и чтения событий в реальном времени. Он говорит на JSON, авторизуется по рабочему пространству и работает с любым HTTP-клиентом, включая curl. Текущая версия — v3.

Два адреса. Чтение и подписка идут через edge-узлы https://cdn.internet-backend.ru — они обслуживают только безопасные методы чтения (GET, HEAD, OPTIONS). Публикация и управление — через origin-API https://api.internet-backend.ru (методы записи, POST/PUT/DELETE). Так запись не кэшируется на edge, а поток доставляется с ближайшего узла.

Доступ и бета

Платформа работает в режиме закрытой беты. Доступ выдаётся по рабочему пространству после проверки — запросите доступ, и вы получите ключи после подтверждения. Эндпоинты доступны, но без валидной сессии вернут 401.

curl -i https://cdn.internet-backend.ru/api/v3/stream
HTTP/2 401
content-type: application/json

{ "error": "unauthorized", "message": "Требуется активная сессия рабочего пространства." }

Аутентификация

Запросы авторизуются по сессии рабочего пространства. Браузерные и долгоживущие потоковые клиенты используют сессионную cookie (PHPSESSID) — это позволяет потоку пережить прокси и CDN, не пересылая учётные данные в каждом запросе. Серверные клиенты могут обменять сессию на bearer-токен в разделе Настройки → API-ключи.

# Браузерные / потоковые клиенты — сессионная cookie
curl -N https://cdn.internet-backend.ru/api/v3/stream \
  --cookie "PHPSESSID=$SESSION"

# Сервер-сервер — bearer-токен
curl https://cdn.internet-backend.ru/api/v3/topics \
  -H "Authorization: Bearer $IB_TOKEN"

Сквозное шифрование

Полезная нагрузка каждого события шифруется на клиенте до отправки. По сети и через наш edge проходит только шифротекст — ключей у нас нет, и содержимое событий мы прочитать не можем. Открытыми остаются лишь служебные метаданные: позиция курсора p и идентификатор запроса.

Обмен ключами — гибридный, пост-квантовый (X25519 + ML-KEM-768). Поэтому тело запроса и ответа выглядит как случайный набор байт:

# так тело события выглядит на сети (payload зашифрован)
data: {"p":128402,"payload":"a1f2…случайный шифротекст…9c7b"}

Ни edge-узел, ни CDN, ни оператор связи не могут восстановить содержимое. Расшифровка возможна только клиентом, у которого есть ключ рабочего пространства.

GET  Подписка на поток

GET /api/v3/stream

Открывает долгоживущий ответ и отдаёт события по мере их появления. Соединение держится открытым; каждое событие приходит отдельным чанком. Параметр topic фильтрует по топику, параметр p задаёт позицию курсора для возобновления.

curl -N "https://cdn.internet-backend.ru/api/v3/stream?topic=orders.*&p=128400" \
  --cookie "PHPSESSID=$SESSION" \
  -H "Accept: text/event-stream"

data: {"p":128401,"payload":"…шифротекст…"}
data: {"p":128402,"payload":"…шифротекст…"}
: heartbeat

Курсор и возобновление

Каждое доставленное событие несёт позицию p — монотонно возрастающий курсор в журнале. Клиент сохраняет последнюю позицию и передаёт её обратно параметром p, чтобы продолжить ровно с места разрыва. События хранятся и доступны для повторного чтения до 30 дней.

Клиент периодически подтверждает продвижение курсора коротким запросом GET /api/v3/stream?p=<позиция> — это нормальная, ожидаемая нагрузка для активной подписки.

POST  Публикация события

POST https://api.internet-backend.ru/api/v3/topics/{topic}/events

Публикация идёт на origin-API api.internet-backend.ru — edge-узлы cdn.* принимают только чтение. Payload уже зашифрован клиентом. Публикация идемпотентна при передаче заголовка Idempotency-Key.

curl -X POST https://api.internet-backend.ru/api/v3/topics/orders.created/events \
  -H "Authorization: Bearer $IB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload":"…шифротекст…"}'

GET  Топики и статус

Список топиков рабочего пространства и проверка здоровья платформы (для health авторизация не нужна).

GET /api/v3/topics    →  {"object":"list","data":[{"id":"announcements","subscribers":128}, …]}
GET /api/v3/health    →  {"status":"operational","version":"3.4.1","region":"ru-central"}

Ошибки

Используются стандартные коды HTTP. 2xx — успех, 4xx — ошибка клиента (с машиночитаемым error), 5xx — ошибка сервера. Потоковые ответы, оборвавшиеся неожиданно, следует повторить с последним курсором.

{ "error": "unauthorized", "message": "Требуется активная сессия рабочего пространства." }

Монитор (расширение для Firefox)

Монитор — наше фирменное расширение для Firefox: показывает события в реальном времени прямо в панели браузера. Фоновый worker открывает одну подписку GET /api/v3/stream на окно и рендерит события локально.

Поскольку браузерный EventSource не умеет добавлять произвольные заголовки, «Монитор» авторизуется сессионной cookie (withCredentials: true) — тем же способом, что описан в разделе Аутентификация. Поэтому потоковые клиенты предъявляют PHPSESSID, а не заголовок Authorization.

// Монитор — background.js (фрагмент)
const es = new EventSource(
  "https://cdn.internet-backend.ru/api/v3/stream?p=" + cursor,
  { withCredentials: true }
);
es.onmessage = (e) => render(decrypt(JSON.parse(e.data)));  // расшифровка локально
es.onerror   = ()  => reconnect(lastCursor);                // возобновление по курсору

Расширение в закрытой бете для Firefox 128+. Сборки для Chrome и Edge — на проверке. Подписанный .xpi высылается после подтверждения доступа.

Статус и доступность

Статус платформы, история инцидентов и региональные задержки публикуются на status.internet-backend.ru. Программная проверка — GET /api/v3/health.