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.
Cache-Control
Section intitulée « Cache-Control »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.
Requêtes conditionnelles
Section intitulée « Requêtes conditionnelles »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.
curl -H 'If-None-Match: W/"5f3a…"' "$IDALGO_API/v1/standings?season=374703"Compression
Section intitulée « Compression »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.
curl --compressed "$IDALGO_API/modules/match-sheet/v1?contest=54732603"Suivre un match en direct
Section intitulée « Suivre un match en direct »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).