Conventions : enveloppe, catégories, pagination et erreurs

Apprenez ces règles une fois, et chaque endpoint se comporte comme prévu.

L’enveloppe de réponse

Chaque réponse réussie est un objet JSON à deux clés :

Clé	Contenu
data	Un objet (ressource unique) ou un tableau (liste)
meta	total, page, size, total_pages — les champs de pagination valent null quand l’endpoint n’est pas paginé

{
  "data": { "year": 2026, "status": "ACTIVE" },
  "meta": { "total": 1, "page": null, "size": null, "total_pages": null }
}

Les noms de champs sont en snake_case partout (rider_number, total_points, season_year).

Catégories : MotoGP, Moto2 et Moto3

Les endpoints par saison acceptent un paramètre de requête category valant MOTOGP, MOTO2 ou MOTO3. class en est un alias aux mêmes valeurs — envoyez l’un ou l’autre, pas les deux.

GET /standings/seasons/2026/riders?category=MOTO2
GET /races/seasons/2026?category=MOTO3

Passez category explicitement pour que le résultat ne dépende jamais d’une valeur par défaut.

Pagination

Les endpoints « tout récupérer » — /riders, /teams, /races et /standings — sont paginés avec page (à partir de 1) et size (1–200, 20 par défaut) :

GET /riders?page=2&size=50

"meta": { "total": 118, "page": 2, "size": 50, "total_pages": 3 }

Bouclez jusqu’à ce que page atteigne total_pages :

async function getAll(path) {
  const rows = [];
  for (let page = 1; ; page++) {
    const { data, meta } = await getEnvelope(`${path}?page=${page}&size=200`);
    rows.push(...data);
    if (!meta.total_pages || page >= meta.total_pages) return rows;
  }
}

Les listes par saison comme /riders/seasons/{year} renvoient toute la saison en une seule réponse.

Ordre

Les classements arrivent triés par position. Les calendriers et résultats de course ne sont pas garantis triés — triez-les vous-même :

races.sort((a, b) => a.round_number - b.round_number);
results.sort((a, b) => a.position - b.position);

Identifiants

Ressource	Recherche par
Pilote	Numéro de course : /riders/{rider_number} (ex. 93)
Équipe	ID opaque issu d’une liste d’équipes : /teams/{id}, ou par nom : /teams/name/{name}
Course	Saison + manche : /races/seasons/{year}/round/{round}, ou ID opaque : /races/{race_id}/results
Saison	Année : /seasons/{year}

Récupérez les ID opaques ("82MQRdM5q7ub4OSm6Jhx") dans une réponse de liste au lieu de les coder en dur, et associez les équipes par ID plutôt que par nom — les noms de sponsors changent d’une saison à l’autre.

Types de classement

Outre les routes dédiées (/riders, /teams, /manufacturers, /bmw-m), vous pouvez demander un classement par type :

GET /standings/seasons/2026/type/MANUFACTURER?category=MOTOGP

Les types sont RIDER, TEAM, MANUFACTURER et BMW_M.

Erreurs

Les erreurs utilisent les codes de statut HTTP standard et un corps JSON :

{
  "timestamp": "2026-01-27T19:18:29",
  "status": 404,
  "error": "Not Found",
  "message": "Rider not found with number: 99",
  "path": "/riders/99"
}

Statut	Signification	Que faire
400	Paramètre invalide (année incorrecte, catégorie inconnue)	Corrigez la requête ; validation_errors liste les problèmes quand il est présent
401 / 403	Clé RapidAPI absente ou invalide, ou aucun abonnement	Vérifiez les deux en-têtes et votre offre
404	Le pilote, l’équipe, la course ou la saison n’existe pas	Affichez un état « introuvable »
429	Limite de débit ou quota de votre offre atteint	Patientez puis réessayez, ou changez d’offre
5xx	Problème serveur temporaire	Réessayez avec un backoff exponentiel ; consultez la page de statut

Cache

Les résultats et classements changent après chaque week-end de course, les profils entre les saisons. Mettez en cache généreusement pour économiser du quota et garder des pages rapides :

Données	Durée de cache conseillée
Saisons, pilotes, équipes, statistiques de carrière	24 heures
Calendrier	12 heures
Résultats et classements	1 heure les week-ends de course, 12 heures sinon

Gardez votre clé côté serveur

Votre clé RapidAPI est un identifiant de facturation. Appelez l’API depuis votre backend, une fonction serverless ou une étape de build — jamais depuis du code navigateur ou mobile qui livre la clé aux utilisateurs. Le guide du tableau de classement montre un petit proxy avec cache.