Inkrementaalinen synkronointi updated_since-parametrilla

Kun pidät kopiota Sursan tiedoista omassa järjestelmässäsi, kaikkea ei tarvitse lukea joka kerta. Niiden objektien listat, joilla on updated_at, hyväksyvät updated_since-parametrin ja palauttavat vain ne objektit, jotka ovat muuttuneet kyseisellä hetkellä tai sen jälkeen.

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"

Kun updated_since on mukana, lista lajitellaan nousevasti ensin updated_at-kentän ja sitten id-kentän mukaan, ja kursori jatkaa samassa järjestyksessä. Näin luet muutokset siinä järjestyksessä kuin ne tapahtuivat, eikä sivun raja koskaan jaa niitä niin, että jokin muutos jää väliin.

updated_since-parametrin hyväksyvät seuraavat listat:

Kokoelmilla, käyttäjillä ja tiedotteilla ei ole updated_at-kenttää, joten niiden listat eivät suodata sen mukaan: listat ovat lyhyitä, joten lue ne kokonaan joka ajokerralla. Ajassa täytyy olla aikavyöhykkeen siirtymä, kuten Z tai +02:00; mikä tahansa muu arvo hylätään, kuten GET /v1/cards -listassa.

Kun updated_since on mukana, kansiopuu ei enää ole puu: kunkin kokoelman folders sisältää muuttuneet kansiot tasaisena listana tyhjällä children-kentällä, ja parent_id kertoo, missä kukin niistä sijaitsee. GET /v1/folders jättää tällöin pois kokoelmat, joissa ei ole muuttuneita kansioita.

Synkronointisilmukka

1. Lue ensimmäisellä ajokerralla koko lista ilman updated_since-parametria ja tallenna hetki, jolloin ajo alkoi.
2. Anna jokaisella seuraavalla ajokerralla tallennettu hetki updated_since-parametrina pienellä varmuusmarginaalilla vähennettynä, esimerkiksi miinus minuutti, ja tallenna uusi alkamisaika.
3. Kirjoita jokainen objekti tallennuspaikkaasi sen id-tunnuksen mukaan niin, että se korvaa edellisen kopion. Varmuusmarginaalin vuoksi kahdesti tulevat objektit yksinkertaisesti kirjoitetaan uudelleen.
4. Pyydä jokainen seuraava sivu kursorilla ja samalla updated_since-parametrilla. Kursori toimii vain ensimmäisen sivun suodattimien kanssa: ilman niitä pyyntö palauttaa 400-vastauksen ja koodin api.cursor_invalid.

Kun käytät ajon alkamisaikaa etkä sen päättymisaikaa, ajon aikana tehty muutos tulee varmasti mukaan seuraavaan ajoon.

GET /v1/cards palauttaa JSON-taulukon, joten sen seuraava sivu tulee X-Next-Cursor-otsakkeessa (ks. Listat, jotka palauttavat taulukon):

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
}

Poistot

Lista palauttaa vain olemassa olevat objektit, joten siitä ei näe, että jotain on poistettu. Poimi poistot tapahtumasyötteestä:

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"

Syötteen lukemiseen tarvitaan avain, jolla on rooli admin ja käyttöalue webhooks:manage. Tapahtumia säilytetään 30 päivää. Jos synkronointisi ei ole ollut käynnissä tätä pidempään, lue koko lista uudelleen ja poista tallennuspaikastasi kaikki objektit, joita listassa ei enää ole.

Vienti tietovarastoon yhdistää listat, updated_since-parametrin ja tapahtumasyötteen yhdeksi työksi.