Cache-Control

L'en-tête (header) HTTP Cache-Control est un en-tête standard utilisé pour définir la politique de cache des contenus, aussi bien dans les requêtes que les réponses. Les règles (ou directives) de gestion du cache ne s'appliquent que dans un sens, donc une règle dans une requête ne signifie aucunement que la même règle sera présente dans la réponse.

Syntaxe

Les règles ne sont pas sensibles à la casse et ont une valeur optionnelle qui peut être une chaîne de caractères entre guillemets ou des mots clefs. Plusieurs règles peuvent être séparées par une virgule.

Règles de cache des requêtes

Les règles standard Cache-Control suivantes peuvent être utilisées par un client HTTP dans une requête :

Cache-Control: max-age=<seconds>
Cache-Control: max-stale[=<seconds>]
Cache-Control: min-fresh=<seconds>
Cache-Control: no-cache 
Cache-Control: no-store
Cache-Control: no-transform
Cache-Control: only-if-cached

Règles de cache des réponses

Les règles standard Cache-Control suivantes peuvent être utilisées par un serveur HTTP dans une réponse :

Cache-Control: must-revalidate
Cache-Control: no-cache
Cache-Control: no-store
Cache-Control: no-transform
Cache-Control: public
Cache-Control: private
Cache-Control: proxy-revalidate
Cache-Control: max-age=<seconds>
Cache-Control: s-maxage=<seconds>

Extensions de Cache-Control

Les règles suivantes ne font pas partie des règles standard de gestion du cache. Pour savoir quels navigateurs supportent ces règles, on pourra se référer à la matrice de compatibilité.

Cache-Control: immutable 
Cache-Control: stale-while-revalidate=<seconds>
Cache-Control: stale-if-error=<seconds>

Directives

Possibilité de mise en cache

Différents composants peuvent gérer un cache. Un cache peut être géré par un navigateur, un serveur mandataire (proxy), un serveur web (en reverse proxy ou utilisé normalement).

public

Indique que la réponse peut être mise en cache par n'importe quel cache.

private

Indique que la réponse ne doit être mise en cache que pour un utilisateur donné et ne doit donc pas être mise en cache par un cache partagé.

no-cache

Indique de renvoyer systématiquement la requête au serveur et ne servir une éventuelle version en cache que dans le cas où le serveur le demande.

only-if-cached

Indique de se limiter au contenu en cache. Dans ce cas, le client ne veut pas que sa réponse soit envoyée au serveur.

Expiration

max-age=<secondes>

Indique la durée pendant laquelle la ressource doit être considérée comme valide (non expirée). Contrairement à expires, la durée indiquée dans cette directive commence à la date de la requête.

s-maxage=<secondes>

Indique une valeur pour écraser les valeurs définies par max-age ou Expires pour les caches partagés (comme les proxies). Il est donc ignoré par les caches privés (dont les navigateurs).

max-stale[=<secondes>]

Indique que le client accepte une réponse expirée. Une valeur optionnelle permet d'indiquer la durée maximale depuis laquelle la réponse peut être expirée mais acceptée quand même.

min-fresh=<secondes>

Indique que le client demande une réponse qui soit valide pour au moins la durée demandée (dont la date d'expiration est supérieure à la date actuelle plus la durée spécifiée).

stale-while-revalidate=<secondes>

Indique au cache de renvoyer les données en cache même si elles sont expirée depuis une durée inférieure à la durée spécifiée dans l'en-tête. Dans ce cas, le cache doit renvoyer la requête au serveur pour rafraîchir les données.

stale-if-error=<secondes>

Indique au cache de renvoyer les données en cache s'il y a une erreur pendant la récupération des données auprès du serveur et que la version en cache est expirée depuis une durée inférieure à celle spécifiée dans l'en-tête.

Revalidation et rechargement

must-revalidate

Le cache doit refaire une requête dans le cas où les données sont expirées afin de les mettre à jour s'il y a lieu (il reste parfaitement possible que le serveur réponde avec les mêmes données).

proxy-revalidate

Comme pour must-revalidate, mais force la valeur pour les caches partagés. Cette valeur est ignorée par les caches locaux.

immutable

Indique que les données renvoyées peuvent être servies même si elles sont expirées sans aucune validation et même si le client fait une demande explicite de rafraîchissement. Cette option est a priori uniquement adaptée si les contenus ne sont jamais modifiés mais toujours stockés à une URI différente (par exemple en utilisant un hash du contenu). Les clients qui ne gèrent pas cette directive l'ignorent. Dans le cas de Firefox, cette option est aussi ignorée pour les contenus qui ne sont pas servis en HTTPS. Pour plus d'informations, on pourra se référer à un blog en anglais.

Autres

no-store

La requête ou les données ne devraient jamais être mises en cache.

no-transform

Aucune conversion ou transformation ne devraient être réalisée sur la ressource. Ainsi, les en-tête Content-Encoding, Content-Range et Content-Type ne devraient jamais être modifiés par un proxy (serveur mandataire). Un proxy non-transparent pourrait, en l'absence de cet en-tête, convertir ou compresser (avec pertes) des images pour réduire la place occupée en cache ou diminuer le volume de données à transférer sur un lien lent.

Exemples

Empêcher la mise en cache

Pour désactiver la mise en cache, il est possible d'envoyer l'en-tête suivant :

Cache-Control: no-cache, no-store, must-revalidate

Il est aussi pertinent de renvoyer des en-tête Expires et Pragma adaptés.

Mise en cache des fichiers statiques

Pour les fichiers de l'application qui ne seront pas modifiés, il est en général possible de définir une politique de cache pendant une longue période. Ceci s'applique particulièrement aux images, feuilles de style CSS et scripts JavaScript. Vous pouvez aussi regarder l'en-tête code>Expires.

Cache-Control: public, max-age=31536000

Spécifications

Compatibilité avec les navigateurs

La matrice de compatibilité de cette page est générée depuis le dépôt Git https://github.com/mdn/browser-compat-data. Si vous voulez contribuer en modifiant ces données, merci de faire une pull request sur Github.

No compatibility data found. Please contribute data for "http/headers/cache-control" (depth: Cache-Control) to the MDN compatibility data repository.

Voir aussi

• HTTP Caching FAQ
• Age
• Expires
• Pragma