AttendBeacon
Open de werkruimte

Concepten

Paginering en synchronisatie

Lijsten antwoorden per pagina met een cursor; updatedSince haalt alleen op wat er sinds je vorige keer is veranderd.

Pagina's en cursors

Elke lijst antwoordt op dezelfde manier: de items, de cursor voor de volgende pagina, en of die er is.

JSON
{
  "data": [ { "sessionId": "b3ac0004-0000-4000-8000-000000000000", "title": "Registration and coffee" } ],
  "nextCursor": "YzE6MDYzOTI3NjEwODQ4MjgyMDAwMHxiM2Fj...",
  "hasMore": true
}

Geef nextCursor terug als cursor, met dezelfde filters, tot hij null is. limit bepaalt de paginagrootte: standaard 100, hoogstens 500. Een cursor is ondoorzichtig: bewaar hem zoals hij kwam en bouw er zelf geen. Een cursor die de server niet heeft gemaakt, wordt geweigerd met invalidCursor in plaats van dat er stilletjes opnieuw wordt begonnen.

Lijsten hebben een vaste volgorde, de oudste wijziging eerst, met de id als scheidsrechter, zodat een pagina nooit een item overslaat of herhaalt dat tijdens het lezen niet veranderde. Een item dat verandert terwijl je bladert, schuift naar het einde en je ziet het nog een keer, en dat is precies wat een synchronisatie wil.

De lijsten van deelnemers, bestellingen en check-ins nemen ook nog de page en pageSize die ze namen voordat er cursors waren. Die werken nog; gebruik liever de cursor, die nooit hoeft te tellen.

Synchroniseren: alleen wat veranderde

Lijsten van dingen die veranderen, zeggen in updatedUtc wanneer elk item het laatst veranderde, en nemen updatedSince. Een synchronisatie onthoudt de nieuwste updatedUtc die ze zag en vraagt de volgende keer vanaf daar:

  1. Lees elke pagina met updatedSince ingesteld op wat je de vorige keer hebt bewaard (de eerste keer niets).
  2. Sla elk item op of werk het bij, op basis van de id.
  3. Bewaar de nieuwste updatedUtc van deze ronde voor de volgende keer.

updatedSince is inclusief: een item dat in dezelfde milliseconde veranderde als je markering, komt opnieuw mee in plaats van gemist te worden. Een item bijwerken dat je al hebt, kan geen kwaad; er een missen wel.

const base = "https://attendbeacon.com/api/v1/events/b3ac0000-0000-4000-8000-000000000001/attendees";
const headers = { Authorization: `Bearer ${process.env.ATTENDBEACON_KEY}` };

let since = await loadMark();              // null on the first run
let newest = since;
let cursor = null;

do {
  const url = new URL(base);
  url.searchParams.set("limit", "500");
  if (since) url.searchParams.set("updatedSince", since);
  if (cursor) url.searchParams.set("cursor", cursor);

  const page = await fetch(url, { headers }).then((r) => r.json());
  for (const attendee of page.data) {
    await upsert(attendee);                // by attendee.attendeeId
    if (!newest || attendee.updatedUtc > newest) newest = attendee.updatedUtc;
  }
  cursor = page.nextCursor;
} while (cursor);

await saveMark(newest);

Tijden zijn ISO 8601 in UTC, met drie decimalen en een Z, zodat ze ook als tekst correct vergelijken.

Wat geen wijzigingstijd heeft

Zalen, tracks, sprekers, sponsors en sponsorniveaus zijn kleine lijsten zonder eigen wijzigingstijd: lees ze in hun geheel, met de cursor als je wilt. Hun afzonderlijke resources en het evenement zelf antwoorden met een ETag, dus opnieuw vragen met If-None-Match geeft 304 Not Modified, zonder body, als er niets veranderde.

Check-ins veranderen nooit meer als ze eenmaal zijn gedaan: blader erdoor met cursor, of met after, de laatste checkInId die je hebt, die alleen maar groeit.

Verwijderingen en wissen

Een geannuleerd ticket blijft in de lijst staan met "status": "cancelled", zodat een synchronisatie de annulering ziet. Als iemand de eigen gegevens verwijdert in de evenementapp, blijft de deelnemer staan met "erased": true en zonder iets persoonlijks; de webhook attendee.erased laat het je meteen weten, zodat je je eigen kopie kunt verwijderen. Zie Privacy en wissen.

Webhooks of pollen

Elke paar minuten pollen met updatedSince is eenvoudig en vangt alles. Webhooks laten het je binnen seconden weten. Veel integraties doen allebei: webhooks voor de snelheid, een nachtelijke synchronisatie voor de zekerheid.

De handleidingen en deze site zijn in jouw taal. De beschrijvingen in de API-referentie zelf zijn in het Engels, de taal van de API.