Datensynchronisation über API

1) Warum Synchronisation notwendig ist und welche Ziele

Domain-Konsistenz: Profil, Wallet, Verzeichnisse, Limits, KYC.
Reduzierte Verzögerungen: Fast Echtzeit für kritische Prozesse (Zahlungen, Boni).
Resilienz: Wir erleben Netz-/Anbieterausfälle ohne Veranstaltungsverlust.
Wirtschaftlichkeit: Minimierung von egress/CPU durch Deltas und Packaging.

Erfolgsmetriken: Lag (s) zwischen Quelle und Verbraucher, Freshness, Duplikatanteil, Konfliktprozentsatz, GB-Wert/Stunde Synk.

2) Synchronisationsmodelle

2. 1 Pull (polling)

Der Kunde fordert Änderungen in Intervallen an.

Vorteile: Einfachheit, Laststeuerung.
Nachteile: Lag, „leere“ Umfragen, das Risiko, bei hoher Änderungsrate zu verpassen.
Verbesserungen: If-Modified-Since, Etag/If-None-Match, change_token.

2. 2 Push (webhooks/events)

Die Quelle flufft die Ereignisse zum Empfänger.

Vorteile: fast Echtzeit, Einsparungen bei Umfragen.
Nachteile: Lieferung mit Retrays, Deduplizierung, Sicherheit (Signatur, mTLS) erforderlich.
Anforderungen: idempotente Consumer, exponentieller Backoff, Replay.

2. 3 CDC/Streaming (Datenaufnahme ändern)

Momentaufnahme der Änderungen aus dem Transaktionsprotokoll/Ereignisprotokoll (Kafka, Debezium).

Vorteile: Vollständigkeit, Ordnung, Maßstab.
Nachteile: Komplexität, Sie brauchen die Kontrolle über die Arten von Operationen (insert/update/delete/tombstone).

2. 4 Hybrid

Webhooks als „Trigger“, Polling als Fallback und für Reconciliation.

3) Inkrementelle Deltas

3. 1 Wasserzeichen (Zeitstempel)

Der Kunde speichert 'last _ seen _ ts' und fordert 'updated _ at> watermark' an.

Risiken: Stundendrift - Verwenden Sie UTC und NTP; nehmen Sie das überlappende Fenster (overlap) 1-2 Minuten und dedup durch ID + version.

3. 2 Change Token / Cursor

Stabiles Sequenz-Token:'? cursor = eyJvZmZzZXQiOjEwMDB9'.

Vorteile: Widerstand gegen die Änderung der Ordnung, Maßstab.
Anforderungen: unerschöpfliche Cursor, TTL und sicheres Replay.

3. 3 Nummerierte Offsets (Auto-Increment)

`id > last_id`. Einfach, aber bricht beim Scharren und „Löcher“ in der Reihenfolge.

4) Pagination von großen Proben

Keyset/cursor (bevorzugt):'? after = cursor & limit = 1000'- stabil bei Änderungen.
Offset/Limit - einfach, aber teuer und anfällig für Verschiebungen.
Geben Sie immer einen Stable-Sort-Schlüssel an (z. B.'(updated_at, id)').

json
{
"items": [ { "id": "u_1", "updated_at": "2025-11-03T16:59:10Z" } ],
"next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0xMS0wM1QxNjo1OToxMFoifQ==",
"has_more": true
}

5) Die Semantik der Veränderung: upsert, merge, delete

5. 1 Upsert/merge

'PUT/resource/{ id}' ist ein vollständiger Ersatz.
„PATCH/resource/{ id}“ - teilweise Aktualisierung (Merge-Patches mit Validierung).
Idempotenz durch 'Idempotency-Key' für alle write.

5. 2 Löschungen

Soft delete (Feld 'deleted = true', 'deleted _ at') - Geschichte speichern; sink gibt tombstone.
Hard delete - Geben Sie das Ereignis „deleted“ vor dem Verschwinden.

json
{ "id":"u_1", "event":"deleted", "deleted_at":"2025-11-03T17:00:00Z" }

6) Versionskontrolle und Wettbewerb

6. 1 ETag/If-Match (optimistische Sperren)

Beim Lesen wird 'ETag:' v123 'zurückgegeben.
Update mit 'If-Match:' v123'- Schutz vor „verlorenen Updates“.
In einem Konflikt - 409 Conflict mit 'error _ code:' CONFLICT_VERSION"'.

6. 2 Versionierung von Datensätzen

Feld 'version '/' updated _ at' - in der Berechnung von Deltas und Deduplizierung.

6. 3 Konflikte

Richtlinien: last-write-wins, server-wins, merge-strategy nach Feldern (z. B. Summen → additiv, Flags → Quellpriorität).

7) Bestellung und Deduplizierung

7. 1 Reihenfolge der Lieferungen

Garantien: at-least-once plus idempotence → de facto der Standard.
Für kritische Cashflows - exactly-once Effekte durch den idempotency store.

7. 2 Schlüssel zur Idempotenz

Zusammensetzung der Domänenfelder: 'source _ id' event _ type' sequence'.
TTL-Speicher 24-72 Stunden (oder mehr mit SLA).

7. 3 Deduplizierung

Speichern Sie die zuletzt angewendete Version/Seq auf dem Empfänger; Werfen Sie die älteren weg.

8) Wiederholungen, Timeouts, Backoff

Rückrufbar: 5xx/429/408/timeouts; Non-retriable: 400/401/403/404/409/422/410/412.
Exponentieller Backoff + Jitter: 1s, 2s, 4s... bis 30-60s.
Retry-After Respekt für 429/503.
Client-Timeouts: Verbindung 3-5c, allgemeine Anfrage 10-30c; Gesamtgrenze der Versuche 3-6.

9) Lag- und SLA-Kontrolle

9. 1 SLI/SLO

SLI Lag: Median/p95 lag zwischen „occurred _ at“ und „angewendet beim Verbraucher“.
SLO: zum Beispiel "p95 lag ≤ 60s (28d)", "Anteil der verlorenen Ereignisse = 0", "Anteil der Duplikate ≤ 0. 01%».
Error Budget: Wir geben für Veröffentlichungen/Experimente aus.

9. 2 Metriken

`sync_lag_seconds`, `events_received_total`, `events_applied_total`, `duplicates_total`, `conflicts_total`, `retries_total`, `backlog_size`, `cursor_advance_rate`.

10) Reconciliation (Abstimmung) und Backfill

Tages-/Stundenabgleiche: Gesamtzahlen/Hashes pro Fenster.
Abgleich API: 'GET/reconciliation? from =... & to =... 'gibt Prüfsummen und Varianzen zurück.
Backfill: sicheres Herunterladen historischer Daten in Packungen mit einem Cursor, ohne DDOS-Quelle; Beachten Sie die Grenzen.

11) Schemata und Beispiele

11. 1 Webhook Veranstaltungen (signiert)

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 Inkrementelle Probenahme (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) Sicherheit und Compliance

Auth: OAuth2 scopes/JWT; für Sync-Kanäle - mTLS bei Bedarf.
Bildunterschriften: HMAC Titel für Webhooks, Rotation Geheimnisse.
PII-Minimierung, Maskierung in Protokollen; DSGVO/DSAR: Hochladen/Löschen.
RBAC/ABAC: Zugang nach Tenant/Organisation, strenge Quoten.

13) Beobachtbarkeit und Protokolle

Лейблы: `env`, `service`, `tenant`, `source`, `cursor`, `seq`, `event_type`.
Korrelation: 'trace _ id' aus dem Eingang → in Logs und Tracks anwenden.
Dashboards: lag, backlog, cursor speed, bugs by type, 429/5xx, cost (egress/min).

14) FinOps: Synchronisierungskosten

Batch (Batch-Größe 100-1000) + Komprimierung (gzip/br).
Caching und ETag für unveränderte Seiten.
Thin payload's: nur geänderte Felder, Link zur kompletten Ressource bei Bedarf.
Grenzen der Parallelität und „Nachtfenster“ für Backfill.

15) Prüfung und Qualität

15. 1 Verträge und Negativfälle

Validieren Sie JSON-Schemata, Pflichtfelder, Stabilität 'error _ code'.
Tests: Out-of-Order, Duplikate, Event-Skipping, Versionskonflikt, 429/5xx.

15. 2 Chaos/Spiele

Injektionen: Netzwerkverzögerungen, Drop 10-30% der Ereignisse, Nachbestellung.
Kriterien: Ordnung/Integrität gewahrt? keine Verluste? Lag innerhalb des SLO?

16) Checkliste Umsetzung

• Modell (Push/Pull/Hybrid) und Quelle der Wahrheit ausgewählt.
• Inkrementelle Deltas: Wasserzeichen oder Cursor/Token.
• Pagination: Cursor/Keyset mit stabiler Sorte.
• Idempotency-store, Schlüssel und TTL; dedup durch'(id, version/seq)'.
• ETag/If-Match und Konfliktrichtlinie (LWW/server-wins/merge).
• Retry/backoff/jitter, respect „Retry-After“.
• die Metriken lag/backlog/duplicates/conflicts, deschbordy und alerty.
• Reconciliation API + tägliche Abstimmungen.
• Sicherheit: OAuth2/JWT, Webhook-Signaturen, mTLS, PII-Richtlinien.
• FinOps: batch + compression, limits of parallelism, egress quotes.
• Testkit: Nachbestellung, Duplikate, Outages, Backfill.

17) Implementierungsplan (3 Iterationen)

1. MVP (1-2 Wochen):

Cursor-Pagination, Wasserzeichen-Deltas, idempotente Upsert, Basis-Lag/Backlog-Metriken, Retry + Backoff.

2. Scale (2-3 Wochen):

Webhooks als Auslöser + Polling-Fallback, HMAC-Signaturen, Reconciliation, ETag/If-Match, Dashboards und Burn-Alerts per Lag.

3. Pro (3-4 Wochen):

CDC/Streaming (Kafka/Debezium) für Hot Domains, Auto-Backfill, DR-Skripte, FinOps-Optimierung (Batch/Brotley), SLA nach Lag und Reporting.

18) Mini-FAQ

Was soll man wählen: Wasserzeichen oder Cursor?
Cursor/Keyset ist widerstandsfähiger gegen Nachbestellung und Skalen; watermark ist einfacher zu starten, aber fügen Sie overlap und dedup.

Brauchen Sie exactly-once?
Im Allgemeinen teuer. Praxis - at-least-once + Idempotenz; exactly-once - nur für monetäre Effekte.

Wie können Konflikte minimiert werden?
Verwenden Sie ETag/If-Match, gestalten Sie Merge nach Feldern, vermeiden Sie „versteckte“ Nebenwirkungen.

Summe

Zuverlässige Synchronisation ist inkrementelle Deltas + korrekte Paginierung + Idempotenz und Versionskontrolle, verstärkt durch Beobachtung, Funkeln und sparsamen Transport. Wählen Sie das richtige Modell aus (Push/Pull/CDC), sichern Sie SLOs per Lag, implementieren Sie Konfliktrichtlinien und Dirty-Scripting-Tests - und Ihr Datenaustausch wird vorhersehbar, nachhaltig und wirtschaftlich.