Lappušošana

Sursa API saraksti tiek dalīti lapās ar kursoru: jūs pieprasāt līdz limit elementiem, un atbilde pasaka, kā iegūt nākamo lapu. Nobīdes jums nekad nav jāaprēķina, un elementi starp lapām neatkārtojas un nepazūd, ja dati tikmēr mainās.

Saraksts atgriež nākamo kursoru vienā no diviem veidiem atkarībā no savas atbildes formas. Katras operācijas lapā API rokasgrāmatā ir redzams, kuru veidu tā izmanto.

Saraksti ar datu aploksni

Saraksti, kas pievienoti publiskajam API, piemēram, notikumu plūsma, atgriež objektu ar elementiem laukā data:

curl "https://api.sursa.com/v1/webhook-events?limit=2" \
  -H "Authorization: Bearer $SURSA_API_KEY"

{
  "data": [
    {"id": "evt_8a1f…", "type": "card.published", "created_at": "2026-10-24T10:00:00Z"},
    {"id": "evt_8a20…", "type": "card.updated", "created_at": "2026-10-24T10:00:03Z"}
  ],
  "next_cursor": "eyJ2IjoxLCJrIjpbMTA0Ml19",
  "has_more": true
}

Ja has_more ir true, pieprasiet nākamo lapu ar cursor, kas iestatīts uz next_cursor, un tiem pašiem filtriem:

curl "https://api.sursa.com/v1/webhook-events?limit=2&cursor=eyJ2IjoxLCJrIjpbMTA0Ml19" \
  -H "Authorization: Bearer $SURSA_API_KEY"

Saraksti, kas pastāvēja pirms kursoru ieviešanas un atgriež objektu, saglabā savu aploksni (piemēram, {"items": […], "total": 120}). Tie saņem next_cursor un has_more tajā pašā objektā; elementi paliek, kur bija.

Saraksti, kas atgriež masīvu

Daži saraksti atgriež vienkāršu JSON masīvu, piemēram, GET /v1/collections. To atbildes formu nevar mainīt, tāpēc nākamā lapa tiek padota galvenēs:

curl -i "https://api.sursa.com/v1/collections?limit=50" \
  -H "Authorization: Bearer $SURSA_API_KEY"

HTTP/1.1 200 OK
Link: <https://api.example.com/v1/collections?limit=50&cursor=eyJ2IjoxLCJrIjpbNTBdfQ>; rel="next"
X-Next-Cursor: eyJ2IjoxLCJrIjpbNTBdfQ

[{"id": 1, "name": "support", …}, …]

• Link ar rel="next" ir pilna nākamās lapas adrese; X-Next-Cursor ir tas pats kursors atsevišķi.
• Ja nav ne Link ar rel="next", ne X-Next-Cursor, šī ir pēdējā lapa.
• Bez limit šie saraksti atgriež visus elementus vienā atbildē, kā vienmēr. Nododiet limit, lai tos dalītu lapās; kursors atceras lapas izmēru, tāpēc nākamajā pieprasījumā limit var izlaist.
• Izņēmums ir GET /v1/cards: tas vienmēr atgriež lapas, pēc noklusējuma pa 200 kartītēm un ar limit līdz 1000, tāpēc sekojiet X-Next-Cursor arī bez limit.

// Every item of a list that returns an array.
async function* listArray(path) {
  let next = `https://api.sursa.com${path}?limit=200`;
  while (next) {
    const response = await fetch(next, { headers: { Authorization: `Bearer ${process.env.SURSA_API_KEY}` } });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    yield* await response.json();
    const cursor = response.headers.get("X-Next-Cursor");
    next = cursor ? `https://api.sursa.com${path}?cursor=${encodeURIComponent(cursor)}` : null;
  }
}

Notikumu plūsma

Notikumu plūsma GET /v1/webhook-events ir žurnāls, tāpēc tās lappušošana nedaudz atšķiras:

• Notikumi ir augošā secībā, vecākie vispirms.
• next_cursor tiek atgriezts katrā lapā, arī tad, ja has_more ir false. Saglabājiet to un vēlāk vaicājiet vēlreiz ar to pašu kursoru, lai saņemtu notikumus, kas notikuši pa to laiku. Plūsma ir rinda, ko varat lasīt savā tempā.
• Notikums parādās plūsmā aptuveni sekundes laikā pēc izmaiņas, ko tas apraksta, un nekad – pirms notikuma, kas jau ir nolasīts.
• Plūsmā ir visas organizācijas notikumi, tāpēc tās lasīšanai vajadzīga atslēga ar lomu admin un tvērumu webhooks:manage.

Eksports uz datu noliktavu parāda pilnu aptaujas ciklu.

Kursoru noteikumi

• Kursors ir necaurredzama virkne līdz 512 rakstzīmēm. Neparsējiet to un neveidojiet to paši: tā formāts var mainīties.
• Kursors pieder vienam sarakstam un vienai filtru kopai. Kursors, kas ir bojāts, nāk no cita saraksta vai ir nosūtīts ar citiem filtriem, atgriež 400 ar kodu api.cursor_invalid.
• Katram sarakstam ir fiksēta kārtošanas secība, kas beidzas ar unikālu atslēgu, tāpēc katrs elements parādās tieši vienā lapā.
• Saraksti, kas pievienoti ar kursoriem, neatgriež kopējo skaitu; saraksti, kuriem total bija jau iepriekš, to saglabā. Ja kopskaits ir vajadzīgs, skaitiet elementus lasīšanas gaitā.

Lappušošana ar nobīdi

Daži saraksti pieņēma offset jau pirms kursoru ieviešanas un pieņem to joprojām, lai esošās integrācijas turpinātu darboties. Jaunā kodā dodiet priekšroku cursor. offset un cursor nevar apvienot: ja nosūtāt abus, tiek atgriezts 422 ar kodu validation.failed.