Client Sync API

Минимальный контракт доставки контента: один GET-запрос на ключ. Только HTTPS, только чтение. Изменения контракта анонсируем в блоге.

Запрос

GET /api/v1/sync/<key>?did=<device-uuid>&feed=<channel> HTTP/2
Host: sync.yakvndzen.com

Параметр	Где	Обязателен	Описание
`<key>`	path	да	Opaque-ключ клиента, выдаётся при подключении. Персональный: не публикуйте и не встраивайте в клиентские сборки.
`did`	query	да	Идентификатор устройства (UUID), выдаётся при привязке устройства к ключу. Запрос без `did` завершается ошибкой `400`.
`feed`	query	нет	Канал контента: `stable` (по умолчанию) или `beta`. Набор доступных каналов определяется вашим тарифом.

Методы

Только GET и HEAD. Остальные методы отклоняются на границе (403).

GET идемпотентен: повторный запрос с теми же параметрами возвращает тот же снапшот контента. Ретраи безопасны — при сетевых сбоях просто повторяйте запрос, при желании с экспоненциальной паузой.

Ответ 200

Тело — opaque base64-строка (Content-Type: text/plain). Формат интерпретируется только клиентской библиотекой SyncHub; сервер не отдаёт JSON и не документирует внутреннюю структуру тела.
Заголовок Cache-Control: no-store: ответ персональный и не подлежит кэшированию — ни на промежуточных узлах, ни в CDN.
Тело соответствует текущей версии снапшота контента на момент запроса; новая публикация меняет тело ответа при следующем GET.

Диагностика отказа

При отказе (403, 429) может передаваться заголовок X-Sub-Reason — краткая машинная причина для логов поддержки (например key-revoked, rate-limit). Заголовок диагностический: наличие и набор значений контрактом не гарантируются — в логику клиента закладывать его нельзя.

Коды ответов

Код	Значение	Что делать
`200`	Снапшот контента в теле (base64)	Распаковать клиентской библиотекой.
`400`	Некорректный запрос — как правило, отсутствует `did`	Проверить параметры запроса.
`403`	Ключ недействителен или отозван; также так выглядят запросы методами, отличными от GET/HEAD	Перевыпустить ключ через поддержку.
`404`	Ключ неизвестен	Проверить ключ: опечатка, другой контур окружения.
`429`	Превышен лимит запросов	Подождать `Retry-After` секунд и повторить.

Лимиты

Лимит — 60 запросов в минуту на ключ. Лимит пер-ключевой, а не пер-адрес: несколько устройств на одном ключе делят общую квоту, поэтому при большой матрице устройств запрашивайте ключ на платформу (или на сегмент устройств). При превышении сервер отвечает 429 и заголовком Retry-After.

Примеры

curl "https://sync.yakvndzen.com/api/v1/sync/b7f3e9a2c41d?did=3f8a1c62-9d04-4b7e-a1f2-6c39e2b7c1d8&feed=stable"

# нет did -> 400
curl -i "https://sync.yakvndzen.com/api/v1/sync/b7f3e9a2c41d?feed=stable"

# неизвестный ключ -> 404
curl -i "https://sync.yakvndzen.com/api/v1/sync/000000000000?did=3f8a1c62-9d04-4b7e-a1f2-6c39e2b7c1d8"

Чего в API нет

Намеренно: никаких POST-выгрузок, вебсокет-потоков и пагинации. Один GET — один полный снапшот. Крупность фидов решается секционированием внутри тела — как мы это делаем.