Inkrementinė sinchronizacija su updated_since

Kad savo sistemoje laikytumėte Sursos duomenų kopiją, nereikia kaskart skaityti visko. Objektų, turinčių updated_at, sąrašai priima updated_since ir grąžina tik tuos objektus, kurie pasikeitė tuo momentu arba vėliau.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "updated_since=2026-10-23T00:00:00Z" \
  --data-urlencode "limit=200"

Su updated_since sąrašas rikiuojamas pagal updated_at didėjančia tvarka, paskui pagal id, o žymeklis tęsia ta pačia tvarka. Taip pakeitimus skaitote ta tvarka, kuria jie įvyko, o puslapio riba niekada jų neperskiria taip, kad kuris nors dingtų.

updated_since priima šie sąrašai:

Rinkiniai, naudotojai ir pranešimai neturi updated_at, todėl jų sąrašai pagal jį nefiltruojami: jie trumpi, tad kiekvieno paleidimo metu skaitykite juos visus. Laike turi būti laiko juostos poslinkis, pavyzdžiui, Z arba +02:00; bet kokia kita reikšmė atmetama, kaip ir GET /v1/cards atveju.

Su updated_since aplankų medis nebėra medis: kiekvieno rinkinio folders yra pasikeitę aplankai plokščiu sąrašu, su tuščiu children, o parent_id rodo, kur kiekvienas iš jų yra. Tada GET /v1/folders praleidžia rinkinius be pasikeitusių aplankų.

Sinchronizacijos ciklas

1. Pirmą kartą nuskaitykite visą sąrašą be updated_since ir įsiminkite momentą, kai paleidimas prasidėjo.
2. Kiekvieno kito paleidimo metu perduokite įsimintą momentą kaip updated_since, atėmus nedidelę atsargą, pavyzdžiui, vieną minutę, ir įsiminkite naują pradžios laiką.
3. Kiekvieną objektą įrašykite į savo saugyklą pagal jo id – ankstesnė kopija pakeičiama. Objektai, kurie dėl atsargos pasirodo du kartus, tiesiog įrašomi dar kartą.
4. Kiekvieno kito puslapio prašykite su žymekliu ir tuo pačiu updated_since. Žymeklis veikia tik su pirmojo puslapio filtrais: be jų užklausa grąžina 400 su kodu api.cursor_invalid.

Naudojant paleidimo pradžios, o ne pabaigos laiką, užtikrinama, kad pakeitimą, padarytą paleidimui vykstant, paims kitas paleidimas.

GET /v1/cards grąžina JSON masyvą, todėl jo kitas puslapis nurodomas antraštėje X-Next-Cursor (žr. Sąrašai, grąžinantys masyvą):

const BASE = "https://api.sursa.com";
const headers = { Authorization: `Bearer ${process.env.SURSA_API_KEY}` };

async function syncCards(since, saveCard) {
  const startedAt = new Date();
  const params = new URLSearchParams({ limit: "200" });
  if (since) params.set("updated_since", new Date(since.getTime() - 60_000).toISOString());
  let query = params.toString();
  while (query) {
    const response = await fetch(`${BASE}/v1/cards?${query}`, { headers });
    if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    for (const card of await response.json()) await saveCard(card); // write into your store by card.id
    const cursor = response.headers.get("X-Next-Cursor");
    if (cursor) params.set("cursor", cursor); // keep updated_since: the cursor needs the same filters
    query = cursor ? params.toString() : "";
  }
  return startedAt; // pass it as `since` next time
}

Ištrynimai

Sąrašas grąžina tik esamus objektus, todėl negali pranešti, kad kas nors buvo ištrinta. Ištrynimus pasiimkite iš įvykių juostos:

curl -G https://api.sursa.com/v1/webhook-events \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "type=card.deleted" \
  --data-urlencode "created_since=2026-10-23T00:00:00Z"

Juostai skaityti reikia rakto su vaidmeniu admin ir apimtimi webhooks:manage. Įvykiai saugomi 30 dienų. Jei jūsų sinchronizacija nevyko ilgiau, iš naujo nuskaitykite visą sąrašą ir iš savo saugyklos pašalinkite kiekvieną objektą, kurio jame nebėra.

Eksportas į duomenų sandėlį sujungia sąrašus, updated_since ir įvykių juostą į vieną darbą.