Sync

Sync adalah endpoint CDA yang menyinkronkan materi terbit dari sebuah Space secara inkremental (delta). Alih-alih menerima ulang seluruh Content, Media, dan Content Type yang terbit setiap kali, klien menerima seluruhnya satu kali dan menyimpannya (cache) secara lokal, lalu setelah itu hanya menerima yang berubah dan yang terhapus sejak sinkronisasi terakhir untuk memperbarui cache tersebut. Digunakan untuk mengurangi volume transfer pada aplikasi yang harus menyimpan seluruh materi terbit (cache luring, indeks pencarian, build situs statis, dan sejenisnya).

Sinkronisasi berjalan dalam dua tahap. Pertama, lakukan sinkronisasi awal untuk menerima seluruhnya, lalu simpan nextSyncUrl yang ikut dikirim dalam respons. Selanjutnya, panggil sinkronisasi delta menggunakan sync-token yang ada di dalam URL tersebut untuk menerima hanya bagian yang berubah dan terhapus; respons kembali memberikan nextSyncUrl baru, jadi simpan nilai itu dan ulangi prosesnya.

Alur sinkronisasi

1. Sinkronisasi awal: panggil dengan ?initial=true&type=All untuk menerima seluruh materi terbit. nextSyncUrl disertakan di akhir respons.
2. Menyimpan nextSyncUrl: simpan nilai nextSyncUrl yang diterima apa adanya. Di dalam URL ini terdapat sync-token yang dipakai pada panggilan berikutnya.
3. Sinkronisasi delta: panggil kembali menggunakan sync-token dari nextSyncUrl yang telah disimpan. Hanya yang berubah dan yang terhapus sejak sinkronisasi terakhir yang disertakan dalam respons, dan di akhir disertakan nextSyncUrl baru.
4. Pengulangan: simpan nextSyncUrl baru yang diterima, lalu ulangi langkah 3 setiap kali sinkronisasi diperlukan.

sync-token bukan nilai yang Anda buat sendiri, melainkan kursor buram (opaque). Jangan menafsirkan formatnya atau menyusunnya secara manual; teruskan nilai yang diterima dari nextSyncUrl respons sebelumnya apa adanya ke panggilan berikutnya.

Struktur respons

Berikut adalah respons sinkronisasi awal (type=All) dari sebuah Space demo. items berisi campuran entitas terbit dan penanda penghapusan, lalu di akhir terdapat nextSyncUrl yang dipakai untuk sinkronisasi delta berikutnya.

{
  "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"
}

Kunci utama:

• sys.type: jenis amplop yang membungkus respons sinkronisasi, selalu "PageResponse".
• limit: jumlah item yang disertakan dalam satu kali pengambilan.
• items: array yang berisi campuran entitas terbit dan penanda penghapusan. Pada contoh di atas, item pertama adalah Content yang masih ada (beserta isinya), dan item kedua adalah penanda penghapusan (DeletedContent) yang hanya berisi sys tanpa isi. Jenis-jenis item dibahas di bawah pada Jenis item.
• links: objek tautan halaman. Karena Sync menghubungkan halaman berikutnya dan delta berikutnya melalui nextSyncUrl, objek ini dapat kosong.
• nextSyncUrl: jalur yang dipanggil untuk sinkronisasi delta berikutnya. Pakai sync-token dari URL ini apa adanya pada panggilan berikutnya.

fields pada items adalah peta lokal (locale map) utuh yang belum dipilih ke satu bahasa. Seperti productName pada contoh di atas yang bernilai { "ko-KR": "스테인리스 텀블러 500ml" }, setiap nilai field datang sebagai peta yang berisi nilai per Locale. Berbeda dengan pengambilan CDA Content dan CDA Media yang memilih nilai menjadi satu nilai tunggal melalui parameter locale, Sync tidak memilih ke satu bahasa dan mengirimkan seluruh peta apa adanya. Klien menerima peta ini, menyimpannya (cache) secara lokal, dan memilih nilai bahasa yang diinginkan saat diperlukan. Itulah sebabnya Sync tidak memiliki parameter locale.

photo pada contoh di atas bernilai {} (peta kosong) karena tidak ada Media terkait pada Locale mana pun.

Jenis item

items berisi campuran item dengan sys.type yang berbeda-beda. Secara garis besar terbagi menjadi dua, yaitu entitas yang masih ada dan penanda penghapusan.

Penanda penghapusan adalah sinyal bahwa resource tersebut tidak lagi ada dalam materi terbit. Klien melihat sys.id penanda lalu menghapus item terkait dari cache lokal.

Pada sinkronisasi awal, parameter type digunakan untuk memilih apa yang diterima.

Ketika type adalah Content atau DeletedContent, parameter content-type dapat dipakai untuk membatasi hanya pada item yang termasuk dalam Content Type tertentu.

API

Base URL kedua endpoint di bawah ini adalah https://cda.weegloo.com/v1, dan diperlukan token Bearer untuk autentikasi CDA pada header Authorization. Keduanya memakai jalur yang sama, yaitu GET /spaces/{spaceId}/sync, dan membedakan sinkronisasi awal dengan sinkronisasi delta melalui parameter kueri. Berbeda dengan pengambilan Content dan Media, Sync tidak memiliki parameter locale. Nilai datang sebagai peta lokal (locale map) apa adanya.

items yang kosong berarti tidak ada perubahan sejak sinkronisasi terakhir. Meski begitu, nextSyncUrl baru tetap datang, jadi simpan nilai itu lalu pakai apa adanya pada sinkronisasi berikutnya.

Dokumen terkait

• Ikhtisar CDA: Keseluruhan CDA dan perilaku pengiriman bersama.
• CDA Content: Content terbit yang diambil per item dengan hanya memilih nilai satu bahasa.
• CDA Locale: Daftar Locale yang dipakai saat memilih nilai dari peta lokal (locale map) yang diterima melalui sinkronisasi.
• Multibahasa (konsep): Pemilihan nilai Locale dan fallback.