Aller au contenu

Conventions

Toutes les réponses /v1 et des modules partagent la même enveloppe :

{
"data": { "…": "…" },
"meta": { "generatedAt": "2026-10-19T08:00:00.000Z", "version": "v1", "lang": "fr" },
"links": { "self": "/v1/standings?season=374703" }
}
  • data : la ressource, ou un tableau pour une liste ;
  • meta : date de génération, version du contrat (v1 pour /v1, celle du module pour /modules/<nom>/v<n>), langue, et cursor pour une liste (voir Pagination) ;
  • links.self : le chemin de la ressource, paramètres triés.

Les champs sont en camelCase.

Le sport n’apparaît jamais dans l’URL : c’est un filtre (?sport=). Les réponses portent des discriminants pour adapter l’affichage :

  • sport : le sport (code pour le rendu, id pour filtrer) ;
  • kind : la forme d’un classement (league-table aux points, win-percentage au pourcentage de victoires…) ;
  • type : la forme d’un contest (head-to-head pour un match, ranked pour une épreuve classée).

kind et type sont des listes fermées dans une version : chacun fixe la forme de l’objet, et une nouvelle forme ne sera servie qu’à un client qui la demande (paramètre explicite ou nouvelle version). Vous pouvez les traiter de façon exhaustive.

D’autres valeurs sont des listes ouvertes, qui peuvent gagner des valeurs sans changer de version : status d’un contest, code d’un sport, format d’une phase, unit d’un résultat, type et family d’une action, code d’une erreur. Le contrat OpenAPI les décrit en string, avec les valeurs connues dans x-extensible-enum : un client généré ne rejette pas une valeur nouvelle. Traitez-la comme « autre » sans planter, par exemple en affichant statusLabel pour un statut que vous ne connaissez pas.

En paramètre, ces listes sont fermées : ?status= n’accepte que les valeurs connues, une autre renvoie une erreur 400.

?lang= choisit la langue des noms (défaut fr). Une réponse est dans une seule langue ; un nom absent se replie sur l’anglais, puis le français. L’en-tête Accept-Language est ignoré.

Les identifiants sont des chaînes opaques : passez-les tels quels d’une route à l’autre, sans en déduire de sens ni les convertir en nombres.

Chaque route accepte une liste fermée de paramètres. Un paramètre inconnu ou invalide renvoie une erreur 400 plutôt que d’être ignoré silencieusement.

Toutes les erreurs suivent le format application/problem+json (RFC 9457), y compris une route inconnue (404 not-found) et une erreur inattendue (500 internal-error) :

{
"type": "about:blank",
"title": "Season not found",
"status": 404,
"code": "season-not-found",
"detail": "…"
}

Branchez votre traitement sur code, stable, jamais sur title ni detail. La liste est ouverte : traitez un code inconnu selon son status. Une erreur internal-error porte aussi requestId, l’identifiant de la requête (également en en-tête X-Request-Id) à donner au support ; son detail n’est jamais rempli en production.

code Statut Cause
invalid-request 400 Paramètre invalide, inconnu ou manquant
not-found 404 Route inconnue
season-not-found 404 Saison inconnue
day-not-found 404 Journée absente de cette saison
phase-not-found 404 Phase absente de cette saison
team-not-found 404 Équipe inconnue
person-not-found 404 Personne inconnue
contest-not-found 404 Contest inconnu
standings-unavailable 404 Pas de classement pour cette saison
medal-table-unavailable 404 Pas de médailles pour cette saison
leaders-unavailable 404 Pas de classement de joueurs : actions de match incomplètes pour cette saison
person-stats-unavailable 404 Pas de stats de joueur : actions de match incomplètes pour cette saison
bracket-unavailable 404 Pas de tableau : phase qui n’est pas à élimination, ou sport sans tableau
internal-error 500 Erreur inattendue du serveur ; réessayez plus tard