Sincronizzazione dei dati tramite API

1) Perché vuoi sincronizzare e quali sono gli obiettivi

La coerenza dei domini: profilo, portafoglio, cartelle, limiti, KYC.
Riduzione delle corse: quasi real-time per processi critici (pagamenti, bonus).
Resilienza: si verificano interruzioni di rete/provider senza perdita di eventi.
Economia: minimizziamo egress/CPU con delta e pacchetti.

Metriche di successo: lag (s) tra la fonte e il consumatore, freshness, percentuale di duplicati, percentuale di conflitti, costo GB/ora sink.

2) Modelli di sincronizzazione

2. 1 Pull (polling)

Il client richiede modifiche a intervalli.

I vantaggi sono semplicità, controllo del carico.
Contro: lega, sondaggi «vuoti», rischio di omissione ad alta velocità di cambiamento.
Miglioramenti: If-Modified-Since, Etag/If-None-Match, change _ token.

2. 2 Push (webhooks/events)

La sorgente sta invogliando gli eventi al destinatario.

I vantaggi sono quasi real-time, risparmi di sondaggi.
Contro: necessità di spedizioni con retrai, deduplicazione, sicurezza (firma, mTLS).
Requisiti: consumatori Idempotent, backoff esponenziale, replay.

2. 3 CDC/streaming (Change Data Capture)

Istantanea delle modifiche apportate dal login transazioni/registro eventi (Kafka, Debezium).

I vantaggi sono completezza, ordine, scala.
Contro: complessità, è necessario controllare i tipi di attività (insert/update/delete/tombstone).

2. 4 Ibrido

Webhooks come «trigger», polling come fallback e per la riscossione.

3) Delta incrementali

3. 1 Watermark (etichetta temporale)

Il client memorizza "last _ seen _ ts'e chiede" updated _ at> watermark ".

Rischi: deriva oraria - Utilizzare UTC e NTP; prendere la finestra di sovrapposizione (overlap) 1-2 minuti e il dedotto ID + variante.

3. 2 Change Token / Cursor

Il token stabile della sequenza «?»

I vantaggi sono la resistenza all'ordine, la scalabilità.
Requisiti: cursori non fissati, TTL e replay sicuro.

3. 3 Offset numerati (auto-increment)

`id > last_id`. È semplice, ma si rompe con le chiacchiere e i buchi nella sequenza.

4) Paginazione grandi campionamenti

Keyset/cursor (preferibilmente): '? after = cursor & limit = 1000' è stabile per le modifiche.
Offset/limit è semplice, ma costoso e soggetto a cambiamenti.
Scegli sempre lo stabile fort key (ad esempio, '(updated _ at, id)') ').

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

5) Semantica di modifiche: upsert, merge, delete

5. 1 Upsert/merge

PUT/resource/{ id} è una sostituzione completa.
«PATCH/resource/{ id}» è un aggiornamento parziale (merge-patch convalidato).
Idampotenza per «Idempotency-Key» per tutti i write.

5. 2 Eliminazioni

Soft delete (campo deleted = true, deleted _ at) - Salva la cronologia; Il sink dà tombstone.
Hard delete - Restituisci l'evento deleted prima di scomparire.

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

6) Controllo delle versioni e della concorrenza

6. 1 ETag/If-Match (blocchi ottimistici)

La lettura restituisce «ETag:» v123 «».
Aggiornamento con If-Match: «v123» - Protezione dagli aggiornamenti persi.
Durante il conflitto, 409 Conflict con'errore _ code: "CONFLICT _ VARIANTE" ".

6. 2 Versioning dei record

Il campo «variante »/« updated _ at» è in termini di delta e deduplicazione.

6. 3 Conflitti

Criteri: last-write-wins, server-wins, merge-strategy sui campi (ad esempio, gli importi sono additivi, i flag la priorità dell'origine).

7) Ordine e deduplicazione

7. 1 Ordine delle consegne

Garanzie: at-least-once più idampotenza di uno standard di fatto.
Per i flussi di cassa critici - Effetti exactly-once attraverso idempotency store.

7. 2 Chiavi di idempotenza

Composizione dei campi di dominio: 'source _ id' event _ type 'sequence'.
Storage TTL 24-72 ore (o più con SLA).

7. 3 Deduplicazione

Salvare l'ultima versione/seq applicata sul ricevitore; Allontanate quelli più vecchi.

8) Ripetizioni, timeout, backoff

Retriable: 5xx/429/408/timeout; Non-retriable: 400/401/403/404/409/422/410/412.
Backoff esponenziale + jitter: 1s, 2s, 4s... Fino a 30-60s.
Retry-After rispetto per 429/503.
Timeout client: connessione 3-5s, richiesta totale 10-30s; limite totale di tentativi 3-6.

9) Controllo lame e SLA

9. 1 SLI/SLO

SLI LAG - Lite mediana/p95 tra «occurred _ at» e «applicata al consumatore».
SLO: ad esempio, "p95 lag" 60s (28d) "," percentuale di eventi persi = 0 "," quota di duplicati "0. 01%».
Errore Budget - Spendiamo in release/esperimenti.

9. 2 Metriche

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

10) Assemblaggio e backfill

Comprese diurne/orarie: totale/hash per finestre.
Compressione API: "GET/recepcion? from =... & to =... 'restituisce gli importi di controllo e le soluzioni temporanee.
Backfill: dosaggio sicuro dei dati storici con pacchetti di puntatore, senza sorgente DDOS; Rispettate i limiti.

11) Schemi e esempi

11. 1 Evento 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 Campionamento incrementale (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) Sicurezza e compliance

Auth: OAuth2 scopes/JWT; per i canali su richiesta.
I titoli HMAC per i webhoop, la rotazione dei segreti.
Minimizzazione PII, occultamento nei logi; GDPR/DSAR - Carica/rimozione.
RBAC/ABAC: accesso al tenant/organizzazione, quote rigorose.

13) Osservabilità e fogli

Лейблы: `env`, `service`, `tenant`, `source`, `cursor`, `seq`, `event_type`.
Correlazione: 'trace _ id', dall'ingresso del →, applicatelo ai fogli e alle piste.
Dashboard: lag, backlog, velocità del cursore, errori per tipo, 429/5xx, costo (egress/min).

14) FinOps: costo di sincronizzazione

Batch (batch size 100-1000) + compressione (gzip/br).
Cache e ETag per le pagine inesplose.
Thin payload's - Solo campi modificati, collegamento a una risorsa completa su richiesta.
Limiti di parallelismo e finestre notturne per backfill.

15) Test e qualità

15. 1 Contratti e valigette negative

Convalida gli schemi JSON, i campi obbligatori, la stabilità dì errore _ code '.
Test: out-of-order, duplicati, omissione di eventi, conflitto di versione, 429/5xx.

15. 2 Chaos/giochi

Iniezioni: ritardi di rete, drop 10-30% eventi, reorder.
Criteri di conservazione dell'ordine/integrità? Nessuna perdita? Una lega all'interno dello SLO?

16) Assegno-foglio di implementazione

• Il modello selezionato (push/pull/hybrid) e la fonte della verità.
• Delta incrementali: watermark o cursor/token.
• Paginazione: cursor/keyset con varietà stabile.
• Idempotency-store, chiavi e TTL; «id, variante/seq)».
• ETag/If-Match e il criterio di conflitto (LWW/server-wins/merge).
• Retry/backoff/jitter, rispetto «Retry-After».
• Metriche lag/backlog/duplicates/conflicts, dashboard e alert.
• Ricomposizione API + incrociature giornaliere.
• Sicurezza: OAuth2/JWT, firme webhoop, mTLS, criteri PII.
• FinOps: batch + compressione, limiti di parallelismo, quote egress.
• Set di test: reorder, duplicates, outges, backfill.

17) Piano di implementazione (3 iterazioni)

1. MVP (1-2 settimane):

Cursor-paginazione, watermark-delta, idipotente upsert, metriche base lag/backlog, retry + backoff.

2. Scale (2-3 settimane):

Webhooks come trigger + polling-fallback, firme HMAC, reconciazione, ETag/If-Match, dashboard e burn-alert in laga.

3. Pro (3-4 settimane):

CDC/streaming (Kafka/Debezium) per domini caldi, auto-backfill, script DR, ottimizzazione FinOps (batch/brotley), SLA per lag e report.

18) Mini FAQ

Cosa scegliere tra watermark o cursor?
Cursor/keyset è più resistente a reorder e scala; watermark è più facile da avviare, ma aggiungete overlap e deadup.

È necessario exactly-once?
In generale, è costoso. Pratica - at-least-once + idampotenza; exactly-once - solo per gli effetti monetari.

Come ridurre al minimo i conflitti?
Usare ETAG/If-Match, progettare merge sui campi, evitare effetti collaterali «nascosti».

Totale

Una sincronizzazione affidabile è un delta incrementale + una corretta paginazione + idemoticità e controllo delle versioni, migliorato da osservabilità, incrocio e trasporto economico. Selezionare il modello appropriato (push/pull/CDC), fissare il sistema SLO in base al campo, implementare le regole di conflitto e testare gli scenari «sporchi» e rendere prevedibile, sostenibile ed economico lo scambio di dati.