Pagination de l’API Rally Ligues

Trois listes se parcourent page par page : les ligues, les rencontres et les événements. Le même mécanisme sert aux trois.

Lire une page

Deux paramètres de requête règlent la page.

limit : le nombre d’éléments. Il vaut 25 par défaut, 100 au plus.
after : l’id du dernier élément de la page précédente. Sans lui, tu lis depuis le début.

Un limit au-dessus de 100 est refusé, pas rogné. Un limit qui n’est pas un entier l’est aussi. L’API répond INVALID_INPUT.

curl https://gorally.games/v1/matches \
  -H "Authorization: Bearer $RALLY_API_KEY"

const response = await fetch('https://gorally.games/v1/matches', {
  headers: {
    Authorization: `Bearer ${process.env.RALLY_API_KEY}`,
  },
});
const data = await response.json();

import os

import requests

response = requests.get(
    "https://gorally.games/v1/matches",
    headers={"Authorization": f"Bearer {os.environ['RALLY_API_KEY']}"},
    timeout=10,
)
data = response.json()

L’enveloppe

Toute liste paginée rend le même objet.

{
  "object": "list",
  "data": [
    {
      "id": "f4e3d2c1-b0a9-4f8e-8d7c-6b5a4f3e2d1c",
      "categoryId": "e2b4d6f8-1a3c-4e5b-9d7f-0c2e4a6b8d1f",
      "status": "SCHEDULED",
      "teamAId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "teamBId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "scoreA": null,
      "scoreB": null,
      "sets": null,
      "startsAt": "2027-01-13T00:15:00.000Z",
      "revision": 3
    }
  ],
  "has_more": true
}

object vaut toujours list.
data porte les éléments de la page.
has_more vaut true quand il reste des éléments après cette page.

Parcourir toute la liste

Lis la première page, sans after.
Traite data.
Si has_more vaut true, relis avec after égal à l’id du dernier élément de data. Si data est vide, garde le même after, patiente un instant et relis.
Arrête-toi quand has_more vaut false.

let after;
let hasMore = true;
while (hasMore) {
  const url = new URL('https://gorally.games/v1/leagues');
  url.searchParams.set('limit', '100');
  if (after) url.searchParams.set('after', after);
  const page = await (await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.RALLY_API_KEY}` },
  })).json();
  for (const league of page.data) console.log(league.name);
  hasMore = page.has_more;
  if (page.data.length > 0) after = page.data.at(-1).id;
  else if (hasMore) await new Promise((resolve) => setTimeout(resolve, 1000));
}

Un curseur inconnu est refusé avec INVALID_INPUT. Rally ne repart pas du début : tu recevrais une page en double. Ne fabrique pas de curseur, recopie un id reçu.

Ce qui reste stable

Le parcours suit un numéro d’insertion interne, que rien ne déplace. Renommer une ligue ou corriger une rencontre entre deux pages ne la fait ni disparaître ni revenir.

Une écriture dont la transaction est encore en vol est retardée, jamais sautée. Elle apparaît à sa place quand elle est validée, une seule fois. Une page peut donc être plus courte que limit alors que has_more vaut true : continue. Quand cette écriture est juste après ton curseur, data est même vide avec has_more à true. Rien n’est perdu : relis un peu plus tard avec le même after.

Les listes complètes

Les catégories d’une saison et le classement d’une catégorie rendent tous leurs éléments d’un coup. Ils ne prennent ni limit ni after, et leur enveloppe n’a pas de has_more.

Et ensuite

Lis le guide « Limites » : une boucle de pages compte dans ton quota.

Guide suivant : Limites →