Pagination

Chaque opération de liste renvoie une page d’objets à la fois. Vous passez d’une page à l’autre avec un curseur : l’id d’un objet que vous avez déjà.

L’objet list

Une liste renvoie un objet list :

{
  "object": "list",
  "url": "/v1/registrations",
  "has_more": true,
  "data": [
    {
      "id": "SUB-8c3e2a71-0f4b-4d6a-b5e9-27c1d9a4e612",
      "object": "registration",
      "event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30",
      "status": "validated",
      "role": "attendee",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada.lovelace@example.com",
      "ticket": {
        "name": "Full pass"
      },
      "checkin": {
        "checked_in": true,
        "last_checked_in_at": 1810119600
      },
      "created": 1795521600,
      "updated": 1810119600
    }
  ]
}

• data : les objets de la page, [] s’il n’y en a aucun.
• has_more : true si d’autres objets suivent cette page.
• url : le chemin de la liste.

Les objets viennent toujours du plus récent au plus ancien : par created décroissant, puis par id décroissant.

Taille des pages

limit fixe le nombre d’objets d’une page : de 1 à 100, 10 par défaut. Dès que la requête contient un expand[], limit vaut au plus 20 ; au-delà, la requête renvoie 400 parameter_invalid sur limit.

curl -G https://api.masterconf.com/v1/registrations \
  -H "Authorization: Bearer mcf_your_key" \
  --data-urlencode "event=EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30" \
  --data-urlencode "limit=100"

const params = new URLSearchParams({
  "event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30",
  "limit": "100",
});

const res = await fetch(`https://api.masterconf.com/v1/registrations?${params}`, {
  headers: { Authorization: "Bearer mcf_your_key" },
});
const data = await res.json();

import requests

res = requests.get(
    "https://api.masterconf.com/v1/registrations",
    params={"event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30", "limit": "100"},
    headers={"Authorization": "Bearer mcf_your_key"},
)
data = res.json()

La page suivante

Envoyez starting_after avec l’id du dernier objet de la page que vous avez. La réponse contient les objets qui le suivent.

curl -G https://api.masterconf.com/v1/registrations \
  -H "Authorization: Bearer mcf_your_key" \
  --data-urlencode "event=EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30" \
  --data-urlencode "starting_after=SUB-8c3e2a71-0f4b-4d6a-b5e9-27c1d9a4e612"

const params = new URLSearchParams({
  "event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30",
  "starting_after": "SUB-8c3e2a71-0f4b-4d6a-b5e9-27c1d9a4e612",
});

const res = await fetch(`https://api.masterconf.com/v1/registrations?${params}`, {
  headers: { Authorization: "Bearer mcf_your_key" },
});
const data = await res.json();

import requests

res = requests.get(
    "https://api.masterconf.com/v1/registrations",
    params={"event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30", "starting_after": "SUB-8c3e2a71-0f4b-4d6a-b5e9-27c1d9a4e612"},
    headers={"Authorization": "Bearer mcf_your_key"},
)
data = res.json()

Pour parcourir toute une liste :

1. Demandez la première page.
2. Traitez ses data.
3. Tant que has_more vaut true, redemandez avec starting_after égal à l’id du dernier objet de data.

La page précédente

Envoyez ending_before avec l’id du premier objet de la page que vous avez. La page contient les objets qui le précèdent, dans le même ordre, du plus récent au plus ancien. starting_after et ending_before ne vont jamais ensemble : les envoyer tous les deux renvoie parameter_invalid.

Le nombre total

include[]=total_count ajoute total_count, le nombre d’objets de toute la liste. Il est absent si vous ne le demandez pas.

curl -G https://api.masterconf.com/v1/registrations \
  -H "Authorization: Bearer mcf_your_key" \
  --data-urlencode "event=EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30" \
  --data-urlencode "include[]=total_count"

const params = new URLSearchParams({
  "event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30",
  "include[]": "total_count",
});

const res = await fetch(`https://api.masterconf.com/v1/registrations?${params}`, {
  headers: { Authorization: "Bearer mcf_your_key" },
});
const data = await res.json();

import requests

res = requests.get(
    "https://api.masterconf.com/v1/registrations",
    params={"event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30", "include[]": "total_count"},
    headers={"Authorization": "Bearer mcf_your_key"},
)
data = res.json()

Curseurs valides

Un curseur doit être un objet de la même liste : de votre organisation et du parent de la liste. C’est l’event d’une liste d’inscriptions, le call_for_papers d’une liste de communications, et le filtre event d’une liste d’appels à communications, si vous en donnez un. Tout autre id, inconnu ou supprimé, renvoie parameter_invalid sur son paramètre. L’API ne repart jamais en silence du début.

Un objet curseur qui ne passe plus les filtres de la liste fonctionne toujours. Si une inscription qui vous sert de curseur change de statut pendant que vous parcourez status=require_admin_validation, la page suivante repart de sa position.

Tenir une copie à jour

Pour récupérer les objets créés depuis votre dernier passage, parcourez la liste depuis le plus récent et arrêtez-vous au premier id que vous avez déjà.

Les objets créés pendant votre parcours se placent avant votre curseur : ils ne décalent jamais les pages suivantes. Ils apparaîtront en tête lors de votre prochain passage.

Cela ne trouve que les nouveaux objets. Un changement sur un objet que vous avez déjà, comme un nouveau statut, ne le déplace pas dans la liste : relisez-le avec son opération de lecture, ou parcourez toute la liste. La v1 n’a pas de filtre sur updated.

Ce qui coûte plus cher

L’appel le moins coûteux est la page qui suit celle que vous venez de lire. Continuez vers l’avant avec starting_after.

• Un curseur situé loin dans une longue liste, qui ne vient pas d’une page récente, demande plus de lectures à l’API pour être placé. L’appel est plus lent.
• Beaucoup d’objets créés dans la même seconde, comme lors d’un import, sont plus lents à parcourir.

Une limite connue

Un objet peut entrer dans une liste filtrée avec une date created ancienne, par exemple une inscription plus ancienne dont le statut passe à celui que vous filtrez. Si cela arrive au moment même de l’un de vos appels, cet appel peut le manquer. Votre prochain parcours complet le verra.