Синхронізація даних через API
1) Навіщо потрібна синхронізація і які цілі
Узгодженість доменів: профіль, гаманець, каталоги, ліміти, KYC.
Зниження лагів: майже real-time для критичних процесів (платежі, бонуси).
Стійкість: переживаємо перебої мережі/провайдера без втрати подій.
Економіка: мінімізуємо egress/CPU за рахунок дельт і пакетування.
Метрики успіху: lag (s) між джерелом і споживачем, freshness, частка дублікатів, відсоток конфліктів, вартість GB/годину синка.
2) Моделі синхронізації
2. 1 Pull (polling)
Клієнт запитує зміни з інтервалом.
Плюси: простота, контроль навантаження.
Мінуси: лаг, «порожні» опитування, ризик пропуску при високій швидкості змін.
Поліпшення: If-Modified-Since, Etag/If-None-Match, change_token.
2. 2 Push (webhooks/events)
Джерело пушить події одержувачу.
Плюси: майже real-time, економія опитувань.
Мінуси: потрібна доставка з ретраями, дедуплікація, безпека (підпис, mTLS).
Вимоги: ідемпотентні консюмери, експоненціальний backoff, replay.
2. 3 CDC/стрімінг (Change Data Capture)
Знімок змін з логу транзакцій/журналу подій (Kafka, Debezium).
Плюси: повнота, порядок, масштаб.
Мінуси: складність, потрібен контроль типів операцій (insert/update/delete/tombstone).
2. 4 Гібрид
Webhooks як «тригер», polling - як fallback і для reconciliation.
3) Інкрементальні дельти
3. 1 Watermark (часова мітка)
Клієнт зберігає'last _ seen _ ts'і запитує'updated _ at> watermark'.
Ризики: часовий дрейф - використовуйте UTC і NTP; беріть перекриваюче вікно (overlap) 1-2 хв і дедуп по ID + version.
3. 2 Change Token / Cursor
Стабільний токен послідовності: `?cursor=eyJvZmZzZXQiOjEwMDB9`.
Плюси: стійкість до зміни порядку, масштабність.
Вимоги: невичерпні курсори, TTL і безпечний replay.
3. 3 Нумеровані офсети (auto-increment)
`id > last_id`. Просто, але ламається при шардуванні і «дірках» в послідовності.
4) Пагінація великих вибірок
Keyset/cursor (переважно): '? after = cursor & limit = 1000'- стабільно при змінах.
Offset/limit - просто, але дорого і схильне до зрушень.
Завжди вказуйте stable sort key (наприклад,'( updated_at, id)').
json
{
"items": [ { "id": "u_1", "updated_at": "2025-11-03T16:59:10Z" } ],
"next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0xMS0wM1QxNjo1OToxMFoifQ==",
"has_more": true
}5) Семантика змін: upsert, merge, delete
5. 1 Upsert/merge
'PUT/resource/{ id}'- повна заміна.
'PATCH/resource/{ id}'- часткове оновлення (merge-патчі з валідацією).
Ідемпотентність по'Idempotency-Key'для всіх write.
5. 2 Видалення
Soft delete (поле'deleted = true','deleted _ at') - зберігаємо історію; синк віддає tombstone.
Hard delete - віддавайте подію'deleted'перед зникненням.
json
{ "id":"u_1", "event":"deleted", "deleted_at":"2025-11-03T17:00:00Z" }6) Контроль версій і конкуренції
6. 1 ETag/If-Match (оптимістичні блокування)
Читання повертає'ETag: "v123"`.
Оновлення з'If-Match: «v123»'- захист від «втрачених оновлень».
При конфлікті - 409 Conflict з'error _ code: "CONFLICT_VERSION"`.
6. 2 Версіонування записів
Поле'version '/' updated _ at'- в розрахунку дельт і дедуплікації.
6. 3 Конфлікти
Політики: last-write-wins, server-wins, merge-strategy по полях (наприклад, суми → адитивно, прапори → пріоритет джерела).
7) Замовлення та дедуплікація
7. 1 Порядок доставок
Гарантії: at-least-once плюс ідемпотентність → де-факто стандарт.
Для критичних грошовий потоків - exactly-once ефекти через idempotency store.
7. 2 Ключі ідемпотентності
Композиція доменних полів: `source_id|event_type|sequence`.
TTL сховища 24-72 години (або більше при SLA).
7. 3 Дедуплікація
Зберігайте останній застосований version/seq на приймачі; відкидайте старіші.
8) Повтори, таймаути, backoff
Retriable: 5хх/429/408/таймаути; Non-retriable: 400/401/403/404/409/422/410/412.
Експоненціальний backoff + jitter: 1s, 2s, 4s … до 30-60s.
Retry-After поважати для 429/503.
Клієнтські таймаути: з'єднання 3-5с, загальний запит 10-30с; загальний ліміт спроб 3-6.
9) Контроль лагів і SLA
9. 1 SLI/SLO
SLI Lag: медіанний/р95 лаг між'occurred _ at'і «застосовано у споживача».
SLO: наприклад,'p95 lag ≤ 60s (28d)', "частка втрачених подій = 0", "частка дублікатів ≤ 0. 01%».
Error Budget: витрачаємо на релізи/експерименти.
9. 2 Метрики
`sync_lag_seconds`, `events_received_total`, `events_applied_total`, `duplicates_total`, `conflicts_total`, `retries_total`, `backlog_size`, `cursor_advance_rate`.
10) Reconciliation (звірки) і backfill
Денні/годинні звірки: сумарні показники/хеші по вікнах.
API звірки: `GET /reconciliation? from =... & to =...'повертає контрольні суми і розбіжності.
Backfill: безпечне дозавантаження історичних даних пачками з курсором, без DDOS джерела; дотримуйтесь лімітів.
11) Схеми та приклади
11. 1 Webhook події (signed)
json
{
"event": "user. updated",
"id": "evt_01HX",
"occurred_at": "2025-11-03T18:00:05Z",
"sequence": 123456,
"data": { "id": "u_1", "email": "a@b. com", "updated_at": "2025-11-03T18:00:02Z" }
}- `X-Signature: sha256=
- `X-Event-Id: evt_01HX`
- `X-Retry: 0..N`
11. 2 Інкрементальна вибірка (polling)
`GET /v1/users? updated_after=2025-11-03T17: 58:00Z&cursor=...&limit=1000`
11. 3 Idempotent upsert
POST /v1/users
Idempotency-Key: upsert-u_1-20251103T1800Z
{ "id":"u_1","email":"a@b. com","version":124 }
→ 201/200 (stable)12) Безпека та комплаєнс
Auth: OAuth2 scopes/JWT; для каналів сінка - mTLS на вимогу.
Підписи: HMAC заголовки для вебхуків, ротація секретів.
PII-мінімізація, маскування в логах; GDPR/DSAR: вивантаження/видалення.
RBAC/ABAC: доступ по тенанту/організації, строгі квоти.
13) Спостережуваність і логи
Лейбли: `env`, `service`, `tenant`, `source`, `cursor`, `seq`, `event_type`.
Кореляція: 'trace _ id'з входу → застосовуйте в логи і траси.
Дешборди: lag, backlog, швидкість курсору, помилки за типами, 429/5xx, вартість (egress/хв).
14) ФінОпс: Вартість синхронізації
Пакетування (batch size 100-1000) + стиснення (gzip/br).
Кешування та ETag для сторінок, що не змінилися.
Тонкі payload'и: тільки змінені поля, посилання на повний ресурс на вимогу.
Ліміти паралелізму і «нічні вікна» для backfill.
15) Тестування та якість
15. 1 Контракти і негативні кейси
Валідуйте схеми JSON, обов'язкові поля, стабільність'error _ code'.
Тести: out-of-order, дублікати, пропуск подій, конфлікт версій, 429/5xx.
15. 2 Chaos/ігри
Ін'єкції: мережеві затримки, drop 10-30% подій, reorder.
Критерії: зберегли порядок/цілісність? немає втрат? лаг в межах SLO?
16) Чек-лист впровадження
- Вибрана модель (push/pull/hybrid) і джерело істини.
- Інкрементальні дельти: watermark или cursor/token.
- Пагінація: cursor/keyset зі стабільним сортом.
- Idempotency-store, ключі і TTL; дедуп по'( id, version/seq)'.
- ETag/If-Match і політика конфліктів (LWW/server-wins/merge).
- Retry/backoff/jitter, повага'Retry-After'.
- Метрики lag/backlog/duplicates/conflicts, дешборди та алерти.
- Reconciliation API + щоденні звірки.
- Безпека: OAuth2/JWT, підписи вебхуків, mTLS, PII-політики.
- ФінОпс: batch + compression, ліміти паралелізму, egress-квоти.
- Набір тестів: reorder, duplicates, outages, backfill.
17) План впровадження (3 ітерації)
1. MVP (1-2 тижні):
Cursor-пагінація, watermark-дельти, ідемпотентний upsert, базові метрики lag/backlog, retry + backoff.
2. Scale (2-3 тижні):
Webhooks як тригер + polling-fallback, HMAC підписи, reconciliation, ETag/If-Match, дешборди і burn-алерти по лагу.
3. Pro (3-4 тижні):
CDC/стрімінг (Kafka/Debezium) для гарячих доменів, auto-backfill, DR сценарії, FinOps-оптимізація (batch/бротлі), SLA по lag і звітність.
18) Міні-FAQ
Що вибрати: watermark або cursor?
Cursor/keyset стійкіше до reorder і масштабів; watermark простіше для старту, але додайте overlap і дедуп.
Чи потрібен exactly-once?
У загальному випадку дорого. Практика - at-least-once + ідемпотентність; exactly-once - тільки для грошових ефектів.
Як мінімізувати конфлікти?
Використовуйте ETag/If-Match, проектуйте merge по полях, уникайте «прихованих» побічних ефектів.
Підсумок
Надійна синхронізація - це інкрементальні дельти + правильна пагінація + ідемпотентність і контроль версій, посилені спостережуваністю, звірками і економним транспортом. Виберіть відповідну модель (push/pull/CDC), закріпіть SLO по лагу, впровадьте політики конфліктів і тести «брудних» сценаріїв - і ваш обмін даними стане передбачуваним, стійким і економічним.