Sideinddeling

Lister i Sursas API inddeles i sider med en cursor: Du beder om op til limit elementer, og svaret fortæller dig, hvordan du henter den næste side. Du beregner aldrig offsets, og elementer bliver hverken gentaget eller tabt mellem siderne, når data ændres i mellemtiden.

En liste returnerer sin næste cursor på en af to måder, afhængigt af hvordan svaret er opbygget. Siden for hver operation i API-referencen viser, hvilken måde den bruger.

Lister med datakuvert

Lister, der er tilføjet til det offentlige API, fx hændelsesfeedet, returnerer et objekt med elementerne i 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
}

Når has_more er true, så hent den næste side med cursor sat til next_cursor og de samme filtre:

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

Lister, der fandtes før cursorer og returnerer et objekt, beholder deres egen kuvert (fx {"items": […], "total": 120}). De får next_cursor og has_more i samme objekt; elementerne bliver, hvor de var.

Lister, der returnerer et array

Nogle få lister returnerer et rent JSON-array, fx GET /v1/collections. Formen på deres svar kan ikke ændres, så den næste side kommer i stedet i headere:

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 med rel="next" er den fulde adresse på den næste side; X-Next-Cursor er den samme cursor alene.
• Ingen Link med rel="next" og ingen X-Next-Cursor betyder, at dette er den sidste side.
• Uden limit returnerer disse lister alle elementer i ét svar, som de altid har gjort. Angiv limit for at inddele dem i sider; cursoren husker sidestørrelsen, så den næste anmodning kan udelade limit.
• GET /v1/cards er undtagelsen: Den returnerer altid sider, som standard 200 kort og op til 1000 med limit, så følg X-Next-Cursor også uden 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;
  }
}

Hændelsesfeedet

Hændelsesfeedet GET /v1/webhook-events er en log, så sideinddelingen fungerer lidt anderledes:

• Hændelserne står i stigende rækkefølge, ældste først.
• next_cursor returneres på hver side, også når has_more er false. Gem den, og spørg igen senere med den samme cursor for at få de hændelser, der er sket siden. Feedet er en kø, som du kan læse i dit eget tempo.
• En hændelse dukker op i feedet inden for cirka et sekund efter den ændring, den beskriver, og aldrig før en hændelse, der allerede er læst.
• Feedet indeholder hele organisationens hændelser, så du skal bruge en nøgle med rollen admin og scopet webhooks:manage for at læse det.

Eksportér til et datavarehus viser en komplet pollingløkke.

Regler for cursorer

• En cursor er en uigennemsigtig streng på op til 512 tegn. Fortolk den ikke, og byg den ikke selv: Dens format kan ændre sig.
• En cursor hører til én liste og ét sæt filtre. En cursor, der er beskadiget, kommer fra en anden liste eller sendes med andre filtre, returnerer 400 med koden api.cursor_invalid.
• Hver liste har en fast sorteringsrækkefølge, der slutter med en unik nøgle, så hvert element optræder på præcis én side.
• Lister, der er tilføjet med cursorer, returnerer intet samlet antal; lister, der havde et total før, beholder det. Tæl elementerne undervejs, hvis du har brug for et samlet antal.

Sideinddeling med offset

Nogle lister accepterede offset, før cursorer blev indført, og gør det stadig, så eksisterende integrationer bliver ved med at virke. Foretræk cursor i ny kode. offset og cursor kan ikke kombineres: Sender du begge, returneres 422 med koden validation.failed.