Synchronisation des données via l'API

1) Pourquoi la synchronisation est nécessaire et quels sont les objectifs

Cohérence des domaines : profil, portefeuille, catalogues, limites, KYC.
Réduction des marges : quasi-temps réel pour les processus critiques (paiements, bonus).
Résilience : nous vivons des interruptions de réseau/fournisseur sans perte d'événements.
Économie : minimiser l'egress/CPU au détriment des deltas et des packages.

Métriques de succès : lag (s) entre la source et le consommateur, freshness, proportion de doublons, pourcentage de conflits, coût GB/heure de bleu.

2) Modèles de synchronisation

2. 1 Pull (polling)

Le client demande des modifications à intervalles réguliers.

Avantages : simplicité, contrôle de la charge.
Inconvénients : lag, sondages « vides », risque de passage à un taux de changement élevé.
Améliorations : If-Modified-Since, Etag/If-None-Match, change_token.

2. 2 Push (webhooks/events)

La source tire les événements vers le destinataire.

Avantages : temps quasi réel, économie de sondage.
Inconvénients : besoin de livraison avec retraits, déduplication, sécurité (signature, mTLS).
Exigences : consumers idempotent, backoff exponentiel, replay.

2. 3 CDC/streaming (changement de capture de données)

Instantané des modifications du journal des transactions/événements (Kafka, Debezium).

Avantages : exhaustivité, ordre, échelle.
Inconvénients : complexité, vous avez besoin de contrôler les types d'opérations (insert/update/delete/tombstone).

2. 4 Hybride

Webhooks comme « déclencheur », polling comme fallback et pour la reconnaissance.

3) Delta incrémental

3. 1 Watermark (horodatage)

Le client stocke 'last _ seen _ ts'et demande'updated _ at> watermark '.

Risques : dérive horaire - utiliser UTC et NTP ; Prendre la fenêtre de recouvrement (overlap) 1-2 min et le dédup selon ID + version.

3. 2 Change Token / Cursor

Jeton de séquence stable : '? cursor = eyJvZmZzZXQiOjEwMDB9'.

Avantages : résistance au changement d'ordre, échelle.
Exigences : curseurs non durables, TTL et replay sécurisé.

3. 3 Offsets numérotés (auto-incrément)

`id > last_id`. C'est simple, mais ça se casse en chardonnant et en « trous » dans la séquence.

4) Pagination de grands échantillons

Keyset/cursor (de préférence) : '? after = cursor & limit = 1000' - stable aux variations.
Offset/limit - simple, mais coûteux et sujet à des changements.
Indiquez toujours la clé stable (par exemple, '(updated_at, id)').

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

5) La sémantique du changement : upsert, merge, delete

5. 1 Upsert/merge

« PUT/resource/{ id} » est un remplacement complet.
'PATCH/resource/{ id} 'est une mise à jour partielle (correctifs merge avec validation).
Idempotence par 'Idempotency-Key' pour tous les write.

5. 2 Suppressions

Soft delete (champ 'deleted = true', 'deleted _ at') - nous enregistrons l'historique ; le sink donne le tombstone.
Hard delete - Donnez l'événement 'deleted' avant de disparaître.

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

6) Contrôle des versions et de la concurrence

6. 1 ETag/If-Match (blocages optimistes)

La lecture renvoie 'ETag : « v123 ».
Mise à jour avec 'If-Match : « v123 » - protection contre les « mises à jour perdues ».
En cas de conflit - 409 Conflict avec 'error _ code : "CONFLICT_VERSION"'.

6. 2 Versionage des enregistrements

Le champ 'version '/' updated _ at'est dans le calcul de delta et de déduplication.

6. 3 Conflits

Stratégies : last-write-wins, server-wins, merge-strategy par champs (par exemple, montants → additifs, drapeaux → priorité source).

7) Commande et déduplication

7. 1 Ordre de livraison

Garanties : at-least-once plus idempotence → de facto standard.
Pour les flux de trésorerie critiques - effets exactly-once via idempotency store.

7. 2 Clés d'idempotence

Composition des champs de domaine : 'source _ id'event _ type 'sequence'.
Stockage TTL 24-72 heures (ou plus avec SLA).

7. 3 Déduplication

Stocker la dernière version appliquée/seq sur le récepteur ; Jetez les plus anciens.

8) Répétitions, délais, backoff

Retriable : 5xx/429/408/Temporuts ; Non-retriable: 400/401/403/404/409/422/410/412.
Exponentielle backoff + jitter : 1s, 2s, 4s... jusqu'à 30-60s.
Retry-After à respecter pour 429/503.
Temporisation client : connexion 3-5c, demande générale 10-30c ; limite totale de 3 à 6 tentatives.

9) Contrôle des lagunes et SLA

9. 1 SLI/SLO

SLI Lag : lag médian/p95 entre 'occurred _ at' et 'appliqué au consommateur'.
SLO : par exemple, 'p95 lag ≤ 60s (28d)', 'part des événements perdus = 0', 'part des doublons ≤ 0. 01%».
Error Budget : nous dépensons pour des versions/expériences.

9. 2 Métriques

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

10) Reconnaissance (rapprochement) et backfill

Rapprochements jour/heure : indicateurs totaux/hachages aux fenêtres.
API de rapprochement : 'GET/reconciliation ? from =... & to =... 'renvoie les montants de contrôle et les écarts.
Backfill : distribution sécurisée des données historiques par paquets avec curseur, sans source DDOS ; respecter les limites.

11) Schémas et exemples

11. 1 Webhook de l'événement (signé)

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 Échantillonnage incrémental (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) Sécurité et conformité

Auth: OAuth2 scopes/JWT; pour les canaux synk - mTLS à la demande.
Signatures : Titres HMAC pour les webhooks, rotation des secrets.
Minimisation PII, masquage dans les logs ; GDPR/DSAR : déchargement/suppression.
RBAC/ABAC : accès par tenant/organisation, quotas stricts.

13) Observabilité et loges

Лейблы: `env`, `service`, `tenant`, `source`, `cursor`, `seq`, `event_type`.
Corrélation : 'trace _ id'de l'entrée → appliquer dans les logs et les pistes.
Dashboards : lag, backlog, vitesse du curseur, erreurs par type, 429/5xx, coût (egress/min).

14) FinOps : coût de synchronisation

Empilement (batch size 100-1000) + compression (gzip/br).
Mise en cache et et ETag pour les pages non appliquées.
Payload's subtil : uniquement les champs modifiés, lien vers une ressource complète à la demande.
Limites de parallélisme et « fenêtres de nuit » pour backfill.

15) Test et qualité

15. 1 Contrats et cas négatifs

Validez les schémas JSON, les champs obligatoires, la stabilité 'error _ code'.
Tests : out-of-order, doublons, omission d'événements, conflit de versions, 429/5xx.

15. 2 Chaos/jeux

Injections : retards réseau, drop 10-30 % des événements, reorder.
Critères : maintenir l'ordre/intégrité ? pas de pertes ? Une larme à l'intérieur du SLO ?

16) Chèque de mise en œuvre

• Le modèle (push/pull/hybride) et la source de vérité sont sélectionnés.
• Delta incrémental : watermark ou cursor/token.
• Pagination : cursor/keyset avec variété stable.
• Idempotency-store, clés et TTL ; dedup par '(id, version/seq)'.
• ETag/If-Match et la politique de conflit (LWW/server-wins/merge).
• Retry/backoff/jitter, respect de « Retry-After ».
• Métriques lag/backlog/duplicates/conflicts, dashboards et alertes.
• Reconnaissance API + rapprochement quotidien.
• Sécurité : OAuth2/JWT, signatures Web, mTLS, politiques PII.
• FinOps : batch + compression, limites de parallélisme, quotas egress.
• Ensemble de tests : reorder, duplicates, outages, backfill.

17) Plan de mise en oeuvre (3 itérations)

1. MVP (1-2 semaines) :

Cursor-pagination, watermark-delta, idempotent upsert, métriques de base lag/backlog, retry + backoff.

2. Scale (2-3 semaines) :

Webhooks comme trigger + polling-fallback, HMAC signature, reconciliation, ETag/If-Match, dashboards et burn-alert sur la lagune.

3. Pro (3-4 semaines) :

CDC/streaming (Kafka/Debezium) pour les domaines chauds, auto-backfill, DR script, FinOps optimisation (batch/brotch), SLA pour lag et reporting.

18) Mini-FAQ

Que choisir : watermark ou cursor ?
Cursor/keyset est plus résistant à la lecture et à l'échelle ; watermark est plus facile à démarrer, mais ajoutez overlap et dedup.

Ai-je besoin d'exactly-once ?
En général, c'est cher. Pratique - at-least-once + idempotence ; exactly-once - uniquement pour les effets monétaires.

Comment minimiser les conflits ?
Utilisez ETag/If-Match, concevoir merge par champs, éviter les effets secondaires « cachés ».

Résultat

La synchronisation fiable est un delta incrémental + pagination correcte + idempotence et contrôle des versions, renforcé par l'observation, le scintillement et le transport économique. Choisissez le modèle approprié (push/pull/CDC), fixez le SLO par catégorie, mettez en œuvre des politiques de conflit et des tests de scénarios « sales » - et votre échange de données deviendra prévisible, durable et économique.