Démarrage rapide de l’API Rally Ligues

Ce guide te mène de zéro au classement d’une catégorie, lu par l’API. Compte une dizaine de minutes.

Avant de commencer

Ton organisation a le forfait Ligues : c’est lui qui permet d’émettre une clé.
Tu gères l’organisation : seules ces personnes voient l’écran Intégrations.
Ton logiciel tourne sur un serveur. L’API ne répond pas aux appels d’un navigateur.

Il n’y a pas de bac à sable. Une clé rk_live_ agit sur les vraies données de ton organisation. Commence donc par une clé read, qui ne peut rien modifier.

Créer une clé

Dans Rally Ligues, ouvre la page de ton organisation.
Clique sur « Réglages : intégrations (clés d’API et webhooks) ».
Dans « Émettre une clé », donne-lui un nom, par exemple celui de ton logiciel.
Coche seulement la permission read.
Clique sur « Émettre la clé ».
Copie le secret avec « Copier le secret ». Rally ne le montre qu’une fois.

Range le secret dans une variable d’environnement de ton serveur, jamais dans ton code source. Les exemples de ce guide le lisent dans RALLY_API_KEY.

Premier appel : lister tes ligues

Toutes les opérations partent de https://gorally.games/v1. La clé voyage dans l’en-tête Authorization.

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

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

import os

import requests

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

La réponse est une liste. Les ligues sont dans data, et has_more dit s’il reste une page à lire.

{
  "object": "list",
  "data": [
    {
      "id": "5b0c2f9e-8a41-4d6b-9f3e-1a2b3c4d5e6f",
      "name": "Ligue du mardi",
      "sport": "CURLING",
      "sportLabel": null,
      "profile": {
        "key": "CURLING",
        "label": "Curling",
        "version": 3,
        "resourceKind": "SHEET",
        "cadence": {
          "unitsPerMatch": 8,
          "minutesPerUnit": 15,
          "matchesPerNight": 1,
          "scoreTarget": null,
          "seasonWeeks": {
            "min": 10,
            "max": 30
          }
        },
        "vocabulary": {
          "resource": {
            "one": "feuille",
            "many": "feuilles",
            "genre": "F"
          },
          "unit": {
            "one": "bout",
            "many": "bouts",
            "genre": "M"
          },
          "match": {
            "one": "partie",
            "many": "parties",
            "genre": "F"
          },
          "scoreUnit": {
            "one": "point",
            "many": "points",
            "genre": "M"
          }
        }
      },
      "timeZone": "America/Toronto"
    }
  ],
  "has_more": false
}

Trouver une catégorie

Un classement appartient à une catégorie, qui appartient à une saison. Descends ce chemin une fois, puis garde les identifiants.

GET /leagues/{leagueId} rend la ligue et ses saisons, dans seasons.
GET /seasons/{seasonId}/categories rend les catégories de la saison.

Lire le classement

curl https://gorally.games/v1/categories/e2b4d6f8-1a3c-4e5b-9d7f-0c2e4a6b8d1f/standings \
  -H "Authorization: Bearer $RALLY_API_KEY"

const response = await fetch('https://gorally.games/v1/categories/e2b4d6f8-1a3c-4e5b-9d7f-0c2e4a6b8d1f/standings', {
  headers: {
    Authorization: `Bearer ${process.env.RALLY_API_KEY}`,
  },
});
const data = await response.json();

import os

import requests

response = requests.get(
    "https://gorally.games/v1/categories/e2b4d6f8-1a3c-4e5b-9d7f-0c2e4a6b8d1f/standings",
    headers={"Authorization": f"Bearer {os.environ['RALLY_API_KEY']}"},
    timeout=10,
)
data = response.json()

Les équipes arrivent dans l’ordre du classement. rank donne la place, et tied vaut true quand deux équipes partagent la même.

{
  "object": "list",
  "data": [
    {
      "leagueTeamId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Les Pierres",
      "rank": 1,
      "tied": false,
      "played": 4,
      "wins": 3,
      "draws": 0,
      "losses": 1,
      "scoreFor": 29,
      "scoreAgainst": 18,
      "diff": 11,
      "gamePointsFor": 0,
      "gamePointsAgainst": 0,
      "points": 9
    },
    {
      "leagueTeamId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "name": "Les Balais",
      "rank": 2,
      "tied": false,
      "played": 4,
      "wins": 2,
      "draws": 1,
      "losses": 1,
      "scoreFor": 24,
      "scoreAgainst": 21,
      "diff": 3,
      "gamePointsFor": 0,
      "gamePointsAgainst": 0,
      "points": 7
    }
  ]
}

Le classement est calculé à chaque lecture. Pour le suivre, écoute l’événement match.completed par webhook, puis relis le classement.

Et ensuite

Lis le guide « Authentification et scopes » avant de demander plus que read.
Branche les webhooks pour ne plus interroger l’API en boucle.
Garde le guide « Erreurs » sous la main : chaque erreur porte un code stable.

Guide suivant : Authentification et scopes →