Sync

Sync est un endpoint CDA qui synchronise les ressources publiées d'un Space de façon incrémentale (delta). Au lieu de retélécharger à chaque fois l'intégralité des Content, Media et Content Type publiés, le client récupère une fois l'ensemble complet et le met en cache localement, puis ne reçoit ensuite que ce qui a changé et ce qui a été supprimé depuis la dernière synchronisation pour mettre à jour ce cache. On l'utilise pour réduire le volume transféré dans les applications qui doivent conserver l'ensemble des ressources publiées (cache hors ligne, index de recherche, génération de sites statiques, etc.).

La synchronisation se déroule en deux étapes. On récupère d'abord l'ensemble complet par une synchronisation initiale, et on enregistre le nextSyncUrl renvoyé dans la réponse. Ensuite, on appelle une synchronisation delta avec le sync-token contenu dans cette URL pour ne recevoir que les modifications et les suppressions ; la réponse fournit à nouveau un nouveau nextSyncUrl, que l'on enregistre pour répéter l'opération.

Déroulement de la synchronisation

1. Synchronisation initiale : appelez avec ?initial=true&type=All pour recevoir l'ensemble des ressources publiées. Le nextSyncUrl se trouve à la fin de la réponse.
2. Enregistrement du nextSyncUrl : conservez tel quel la valeur nextSyncUrl reçue. Cette URL contient le sync-token à utiliser lors de l'appel suivant.
3. Synchronisation delta : rappelez l'endpoint avec le sync-token du nextSyncUrl que vous avez enregistré. Seuls les éléments modifiés et supprimés depuis la dernière synchronisation figurent dans la réponse, accompagnés à la fin d'un nouveau nextSyncUrl.
4. Répétition : enregistrez le nouveau nextSyncUrl reçu et répétez l'étape 3 chaque fois qu'une synchronisation est nécessaire.

Le sync-token n'est pas une valeur que vous fabriquez vous-même, mais un curseur opaque. N'essayez pas d'en interpréter le format ni de le composer à la main : transmettez tel quel à l'appel suivant la valeur reçue dans le nextSyncUrl de la réponse précédente.

Structure de la réponse

Voici la réponse d'une synchronisation initiale (type=All) sur un Space de démonstration. Les entités publiées et les marqueurs de suppression sont mêlés dans items, et un nextSyncUrl figure à la fin pour la synchronisation delta suivante.

{
  "sys": { "type": "PageResponse" },
  "limit": 15,
  "items": [
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq",
        "type": "Content",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA", "type": "Refer", "targetType": "ContentType" } },
        "createdAt": "2026-06-15T15:16:12.151Z",
        "updatedAt": "2026-06-16T14:31:20.073Z",
        "revision": 3
      },
      "fields": {
        "price": { "ko-KR": 18000 },
        "description": { "ko-KR": "이중 진공 단열로 보온·보냉이 오래갑니다. 500ml 대용량." },
        "photo": {},
        "productName": { "ko-KR": "스테인리스 텀블러 500ml" }
      }
    },
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7O7vFALWs1GJ",
        "type": "DeletedContent",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA", "type": "Refer", "targetType": "ContentType" } },
        "createdAt": "2026-06-15T07:34:41.522Z",
        "updatedAt": "2026-06-15T07:41:57.198Z",
        "revision": 1
      }
    }
  ],
  "links": {},
  "nextSyncUrl": "/v1/spaces/HnQ32YiH/sync?sync-token=165rWhDiuLNoYOwjVQQAYXMA7makztXnhAV3qamYU75jFldqtvaEhMnr29PqsKTAbcoy6xs0iKpafM0KsKfZ2OHtA6pmbpx2pgx5jJ6bFzrkrBvoSvXF8tYZPkbw4X7B2EpCr95lgkQv4UJVCu1SSZIeH2ewzF"
}

Clés principales :

• sys.type : type de l'enveloppe qui englobe la réponse de synchronisation ; toujours "PageResponse".
• limit : nombre d'éléments contenus dans cette réponse.
• items : tableau dans lequel se mêlent les entités publiées et les marqueurs de suppression. Dans l'exemple ci-dessus, le premier élément est un Content vivant (avec son corps), et le second un marqueur de suppression (DeletedContent) qui ne contient que sys, sans corps. Les types d'éléments sont traités plus bas dans Types d'éléments.
• links : objet de liens de pagination. Comme Sync enchaîne la page suivante et le delta suivant via nextSyncUrl, cet objet peut être vide.
• nextSyncUrl : chemin à appeler pour la synchronisation delta suivante. Réutilisez tel quel le sync-token de cette URL lors de l'appel suivant.

Les fields des items sont la map de Locale brute, sans sélection d'une langue unique. Comme le productName de l'exemple ci-dessus qui vaut { "ko-KR": "스테인리스 텀블러 500ml" }, chaque valeur de field arrive sous forme de map contenant les valeurs par Locale. Contrairement aux requêtes CDA Content et CDA Media qui sélectionnent une valeur unique via le paramètre locale, Sync ne choisit pas une langue unique et renvoie la map complète telle quelle. Le client reçoit cette map, la met en cache localement et sélectionne au besoin la valeur de la langue souhaitée. C'est pourquoi Sync ne possède pas de paramètre locale.

Si le photo de l'exemple ci-dessus vaut {} (map vide), c'est qu'aucun Media associé n'existe pour aucun Locale.

Types d'éléments

Dans items se mêlent des éléments de sys.type différents. Ils se répartissent en deux grandes catégories : les entités vivantes et les marqueurs de suppression.

Un marqueur de suppression signale que la ressource ne figure plus dans les ressources publiées. Le client lit le sys.id du marqueur et supprime l'élément correspondant de son cache local.

Lors de la synchronisation initiale, le paramètre type détermine ce que vous recevez.

Lorsque type vaut Content ou DeletedContent, le paramètre content-type permet de limiter le résultat aux seuls éléments appartenant à un Content Type précis.

API

L'URL de base des deux endpoints ci-dessous est https://cda.weegloo.com/v1, et un token Bearer authentifiant CDA est requis dans l'en-tête Authorization. Tous deux partagent le même chemin GET /spaces/{spaceId}/sync et distinguent synchronisation initiale et synchronisation delta par des paramètres de requête. Contrairement aux requêtes Content et Media, Sync ne possède pas de paramètre locale. Les valeurs arrivent sous forme de map de Locale telle quelle.

Un items vide signifie qu'aucune modification n'est intervenue depuis la dernière synchronisation. Dans ce cas aussi, un nouveau nextSyncUrl est fourni ; enregistrez cette valeur et réutilisez-la telle quelle lors de la synchronisation suivante.

Documents connexes

• Aperçu de CDA : l'ensemble de CDA et le comportement de livraison commun.
• CDA Content : Content publié récupéré par requête unitaire avec la valeur d'une seule langue.
• CDA Locale : liste des Locale à utiliser pour sélectionner une valeur dans la map de Locale reçue par synchronisation.
• Multilingue (concept) : sélection des valeurs par Locale et fallback.