Inkrementāla sinhronizācija ar updated_since

Lai savā sistēmā uzturētu Sursas datu kopiju, katru reizi nav jālasa viss. To objektu saraksti, kuriem ir updated_at, pieņem updated_since un atgriež tikai tos objektus, kas mainīti šajā brīdī vai vēlāk.

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"

Ar updated_since saraksts tiek kārtots pēc updated_at augošā secībā, pēc tam pēc id, un kursors turpina šajā pašā secībā. Tāpēc izmaiņas jūs lasāt tādā secībā, kādā tās notika, un lapas robeža tās nekad nesadala tā, ka kāda izmaiņa pazūd.

updated_since pieņem šie saraksti:

Kolekcijām, lietotājiem un paziņojumiem nav updated_at, tāpēc to saraksti pēc tā nefiltrē: tie ir īsi, tāpēc katrā palaišanā izlasiet tos pilnībā. Laikā jābūt norādītai laika joslas nobīdei, piemēram, Z vai +02:00; jebkura cita vērtība tiek noraidīta, tāpat kā GET /v1/cards.

Ar updated_since mapju koks vairs nav koks: katras kolekcijas folders satur mainītās mapes kā vienkāršu sarakstu ar tukšu children, bet parent_id norāda, kur katra no tām atrodas. GET /v1/folders tad izlaiž kolekcijas bez mainītām mapēm.

Sinhronizācijas cikls

1. Pirmajā palaišanā izlasiet visu sarakstu bez updated_since un atcerieties brīdi, kad palaišana sākās.
2. Katrā nākamajā palaišanā nododiet šo atcerēto brīdi kā updated_since, atskaitot nelielu rezervi, piemēram, vienu minūti, un atcerieties jauno sākuma laiku.
3. Ierakstiet katru objektu savā krātuvē pēc tā id, aizstājot iepriekšējo kopiju. Objekti, kas rezerves dēļ parādās divreiz, vienkārši tiek ierakstīti vēlreiz.
4. Katru nākamo lapu pieprasiet ar kursoru un to pašu updated_since. Kursors darbojas tikai ar pirmās lapas filtriem: bez tiem pieprasījums atgriež 400 ar kodu api.cursor_invalid.

Ja ņem palaišanas sākuma laiku, nevis beigu laiku, izmaiņa, kas veikta palaišanas laikā, noteikti tiks paņemta nākamajā palaišanā.

GET /v1/cards atgriež JSON masīvu, tāpēc tā nākamā lapa tiek padota galvenē X-Next-Cursor (sk. Saraksti, kas atgriež masīvu):

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
}

Dzēstie objekti

Saraksts atgriež tikai esošus objektus, tāpēc no tā nevar uzzināt, ka kaut kas ir dzēsts. Informāciju par dzēstajiem objektiem ņemiet no notikumu plūsmas:

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"

Plūsmas lasīšanai vajadzīga atslēga ar lomu admin un tvērumu webhooks:manage. Notikumi tiek glabāti 30 dienas. Ja jūsu sinhronizācija nav darbojusies ilgāk, izlasiet visu sarakstu vēlreiz un izdzēsiet no savas krātuves katru objektu, kura tajā vairs nav.

Eksports uz datu noliktavu apvieno sarakstus, updated_since un notikumu plūsmu vienā darbā.