Aller au contenu

Cache et fraîcheur

Chaque réponse annonce combien de temps elle reste valable. Respecter ces en-têtes rend vos pages plus rapides et évite les appels inutiles.

La durée dépend de la fraîcheur des données :

Données Cache-Control
Historique (saisons finies, matchs anciens) public, max-age=2592000, immutable
Référentiels (sports, compétitions, fiches d’équipe et de personne) public, max-age=86400, stale-while-revalidate=604800
Saison en cours (calendrier, classements, effectifs) public, max-age=300, stale-while-revalidate=300
Matchs du jour public, max-age=60, stale-while-revalidate=60
Vues live (/v1/live/…, /modules/…/live) tant qu’elles se relisent public, max-age=<pollAfter>

Deux modules ne passent jamais en historique tant qu’ils peuvent encore changer : le tableau de phase finale (/modules/bracket/v1) garde la durée d’une saison en cours jusqu’à ce que sa finale ait un vainqueur, même si ses tours joués sont anciens (les tours suivants se remplissent au tirage) ; le Score Center (/modules/score-center/v1) la garde pour un jour passé, dont previousDate et nextDate changent quand un match est reprogrammé.

Une vue live se garde exactement jusqu’à sa prochaine lecture : max-age vaut son meta.pollAfter (60 secondes pour un match à venir, quelques secondes pendant le direct). Quand pollAfter passe à null, elle prend la durée de ses données (matchs du jour, puis historique).

Une erreur 404 est gardée 60 secondes, une 400 ou une 500 jamais.

Chaque réponse 200 porte un ETag. Renvoyez-le en If-None-Match : si rien n’a changé, l’API répond 304 Not Modified sans corps.

Fenêtre de terminal
curl -H 'If-None-Match: W/"5f3a…"' "$IDALGO_API/v1/standings?season=374703"

Envoyez Accept-Encoding : toute réponse de plus de 1 Ko arrive compressée en brotli (br) ou, à défaut, en gzip, 4 à 10 fois plus légère. Les navigateurs et la plupart des clients HTTP l’envoient et décompressent d’eux-mêmes ; avec curl, ajoutez --compressed.

Fenêtre de terminal
curl --compressed "$IDALGO_API/modules/match-sheet/v1?contest=54732603"

Chargez une fois la fiche complète (/v1/contests/{id}), puis relisez seulement sa vue live (/v1/live/contests/{id}) : statut, score, périodes et, pour un match, ses temps forts (highlights : buts, expulsions, tirs au but), rien d’autre. Toutes les actions du match (cartons, remplacements…) sont dans /v1/contests/{id}/actions.

La vue indique quand la relire : meta.pollAfter en secondes, plus court pour les sports rapides, et son Cache-Control dure exactement autant : la relire plus tôt renvoie la même réponse. Un match à venir se relit toutes les minutes, puis au rythme du direct à partir d’un quart d’heure avant son coup d’envoi (et jusqu’à 30 minutes après s’il n’est toujours pas passé en direct). Quand il vaut null, plus rien ne bougera (match terminé, reporté ou annulé, ou dont le statut n’est plus mis à jour plus de 6 heures après son coup d’envoi) : arrêtez de relire.

async function followLive(id, onUpdate) {
const live = await fetch(`${IDALGO_API}/v1/live/contests/${id}`).then((response) =>
response.json(),
);
onUpdate(live.data);
if (live.meta.pollAfter !== null) {
setTimeout(() => followLive(id, onUpdate), live.meta.pollAfter * 1000);
}
}

Pour tous les matchs d’un jour, la même logique s’applique à /v1/live/contests?date=.

Un module de widget peut avoir sa propre route live, avec le même meta.pollAfter : la feuille de match relit /modules/match-sheet/v1/live (en-tête, actions et compositions), la liste de matchs /modules/match-list/v1/live (statut, score et heure des matchs d’une journée), le Score Center /modules/score-center/v1/live (les mêmes, pour les matchs d’un sport sur un jour), le tableau de phase finale /modules/bracket/v1/live (ses tours : scores, cumuls et qualifiés).