Qu'est-ce que le cache d'API ? En-têtes, couches et invalidation

Qu'est-ce que le cache d'API ?

Le cache d'API consiste à stocker une réponse d'API pour que les requêtes identiques suivantes soient servies depuis la copie conservée au lieu de refaire le travail. La copie peut se trouver chez le client, dans un CDN, dans une passerelle d'API ou dans votre application. Une réponse en cache est plus rapide et soulage le backend, mais elle peut être périmée : chaque décision de cache est donc un arbitrage entre vitesse et fraîcheur.

Où les réponses sont mises en cache

• Cache du client ou du navigateur. Un cache privé propre à un utilisateur. Il supprime entièrement l'aller-retour réseau.
• CDN ou reverse proxy. Un cache partagé proche des utilisateurs. Voir réseaux de diffusion de contenu. Il n'aide que pour les réponses identiques pour beaucoup d'utilisateurs.
• Passerelle d'API. Un cache partagé devant vos services, piloté par les règles de la passerelle.
• Cache applicatif. Mémoire du processus ou magasin comme Redis. On met souvent en cache la requête coûteuse ou la valeur calculée plutôt que la réponse HTTP entière.
• Cache de base de données. Tampons et caches de requêtes internes à la base, le plus souvent automatiques.

Les en-têtes HTTP qui le pilotent

La RFC 9111 définit le comportement des caches HTTP. Les principaux en-têtes de réponse sont :

• Cache-Control: max-age=60 : la réponse reste fraîche 60 secondes. s-maxage fixe la fraîcheur pour les caches partagés uniquement.
• Cache-Control: no-cache : la réponse peut être stockée mais doit être revalidée auprès de l'origine avant chaque réutilisation. Cela ne veut pas dire « ne pas mettre en cache ».
• Cache-Control: no-store : aucun cache, privé ou partagé, ne doit stocker la réponse.
• Cache-Control: private : seul un cache privé, comme celui du navigateur, peut la stocker. public autorise les caches partagés et n'est nécessaire que lorsque la requête portait un en-tête Authorization.
• ETag et If-None-Match : le client envoie le validateur conservé et le serveur répond 304 Not Modified sans corps si rien n'a changé.
• Vary : nomme les en-têtes de requête qui modifient la réponse, comme Accept-Language, pour que chaque variante soit mise en cache séparément.
• stale-while-revalidate et stale-if-error : des extensions de la RFC 5861 qui permettent à un cache de servir une copie périmée pendant qu'il la renouvelle, ou quand l'origine est en panne.

Sans aucune information de fraîcheur, les caches peuvent quand même appliquer une fraîcheur heuristique, en général une fraction du temps écoulé depuis Last-Modified. Définissez plutôt Cache-Control explicitement. Le guide MDN sur le cache HTTP propose des exemples.

Exemple

Un point d'accès public, GET /api/v1/products, change quelques fois par heure. Il peut répondre avec Cache-Control: public, max-age=60 et un ETag : un CDN absorbe la plupart des lectures et les clients revalident à peu de frais. Un point d'accès personnalisé, GET /api/v1/me, doit envoyer Cache-Control: private, no-cache avec un ETag : le navigateur peut le garder mais doit d'abord interroger le serveur, et aucun cache partagé ne le stocke. La clé de cache contient l'URL complète, donc une liste paginée doit porter la page ou le curseur dans la query string ; voir pagination d'API.

Stratégies et invalidation

• Cache-aside. L'application consulte le cache, charge depuis la source en cas d'absence et stocke le résultat. Le schéma le plus simple et le plus courant.
• Write-through. Les écritures mettent à jour le cache et la source ensemble. Les lectures restent cohérentes, les écritures ralentissent.
• Expiration par TTL. Les entrées expirent. C'est simple, mais les données peuvent être périmées jusqu'au TTL après un changement.
• Purge au changement. On supprime les clés ou étiquettes concernées quand les données changent. C'est précis, mais chaque écrivain doit savoir quoi purger.
• URL versionnées. Une version ou un hash de contenu dans l'URL crée une nouvelle clé de cache à chaque changement.

L'invalidation est la source de la plupart des bugs de cache. Notre guide sur l'invalidation du cache dans les tests de performance montre comment des caches périmés ou froids faussent les résultats.

Erreurs courantes

• Laisser des réponses personnalisées entrer dans un cache partagé. Marquez-les private. Un cookie seul ne rend pas une réponse privée.
• Vary absent ou trop large. Sans lui, on sert la mauvaise variante. Varier sur User-Agent fragmente tellement le cache qu'il ne sert presque jamais.
• Mettre les erreurs en cache. Un 500 stocké avec une longue fraîcheur continue d'échouer pour tout le monde. Donnez aux réponses d'erreur une fraîcheur courte ou nulle.
• Cache stampede. Quand une clé très demandée expire, de nombreuses requêtes échouent en même temps et frappent l'origine. Utilisez un verrou au rechargement, un rafraîchissement anticipé ou stale-while-revalidate.
• Croire qu'un POST est mis en cache. La RFC 9111 n'autorise la mise en cache d'autres méthodes que GET que si la méthode le permet et définit comment construire la clé, et en pratique les caches stockent rarement les réponses POST. L'idempotence concerne les relances sans risque, pas la possibilité de mise en cache.
• Ne pas mesurer. Sans taux de succès ni charge sur l'origine par point d'accès, impossible de régler un TTL.

Tester et surveiller un cache

Testez le cache de deux façons. Fonctionnellement : envoyez deux fois la même requête et vérifiez les en-têtes et les temps ; une réponse en cache doit être plus rapide et porter les en-têtes de fraîcheur voulus. Sous charge : exécutez le point d'accès avec un cache chaud puis avec des paramètres qui le contournent, et comparez les temps de réponse et la charge qui atteint votre origine dans vos propres métriques. Vous pouvez commencer par un test de charge d'API gratuit. Après la mise en production, la surveillance d'API prend le relais : LoadFocus API Monitoring peut contrôler le code de statut, le corps, les en-têtes et le temps de réponse, de sorte qu'un déploiement qui perd Cache-Control ou ralentit un point d'accès en cache est signalé. Les contrôles gratuits s'exécutent toutes les 5 minutes. Les limites de débit sont aussi liées au cache, car les réponses servies par celui-ci n'atteignent généralement pas le limiteur ; voir les causes courantes de limitation de débit d'API.

Questions fréquentes : cache d'API

Que dois-je mettre en cache en premier ?

Commencez par les points d'accès en lecture lents, très sollicités, qui changent peu et dont la réponse est la même pour beaucoup d'utilisateurs. Mesurez la latence et le volume de requêtes par point d'accès pour choisir.

Quelle est la différence entre no-cache et no-store ?

no-cache permet à un cache de stocker la réponse mais impose une revalidation auprès de l'origine avant chaque réutilisation. no-store demande aux caches de ne pas stocker la réponse du tout.

Puis-je mettre en cache des requêtes POST ?

Rarement. Les caches HTTP stockent surtout des réponses à GET. Certaines API mettent en cache des POST de type recherche dans la couche applicative avec une clé explicite, mais un CDN ou un navigateur ne le fera pas par défaut.

Un CDN, est-ce la même chose que le cache d'API ?

Non. Un CDN est un endroit où l'on met en cache, en périphérie. Le cache d'API couvre toutes les couches, du navigateur à la base de données.

Comment mettre en cache une API GraphQL ?

Les requêtes voyagent généralement dans le corps d'un POST, donc le cache par URL ne s'applique pas. Les options courantes sont les requêtes persistées envoyées en GET ou la mise en cache au niveau du resolver ou de l'application.

Comment savoir qu'une réponse vient du cache ?

Comparez les temps, regardez l'en-tête Age et tout en-tête de statut de cache ajouté par votre CDN, et vérifiez si la requête atteint les journaux de votre origine.