Warmers d’API

Gardez vos endpoints REST et GraphQL au chaud, avec de vraies méthodes, en-têtes, cookies, corps de requête et matrices de configuration.

13 min read

Les API se refroidissent exactement comme le font les pages Web. Si une réponse JSON est coûteuse à créer et est mise en cache sur votre CDN ou votre passerelle, le premier client après l'expiration paie la même pénalité qu'un visiteur de site Web.

API warmers résout ce problème. Ils sont gérés séparément du site Web warmers, sous Compte → API Warmers, et ont leurs propres limites de forfait.

Séparé du site Web warmers

L'API warmers est une fonctionnalité distincte avec son propre droit. Si la section est manquante ou verrouillée, votre forfait ne les inclut pas — voir Plans et limites.

Quand en utiliser un

Situation	Pourquoi une API warmer aide
Une vitrine ou un site sans tête	Le produit, l'inventaire et le contenu JSON sont récupérés à chaque rendu de page. Le réchauffement de ces routes maintient l’ensemble du front-end rapide.
Une API de développeur publique	Les points de terminaison et les exemples de documentation populaires restent réactifs au lieu d'être lents pour celui qui appelle en premier.
Une couche backend pour frontend	Les points de terminaison agrégés répartis sur plusieurs services sont coûteux à reconstruire. Les réchauffer protège les clients mobiles et Web.
Opérations lourdes GraphQL	Une poignée de requêtes dominent généralement le trafic. Réchauffer ces opérations spécifiques est bien plus important que d'appuyer une fois sur `/graphql`.

Une API warmer n'est pas utile pour les points de terminaison qui ne sont jamais mis en cache ou qui sont uniques par utilisateur et n'ont donc aucune copie en cache partagée à remplir.

Créer une API warmer

1
Vérifiez l'API hostname
Les URL de point de terminaison doivent utiliser un hostname vérifié, exactement comme le site Web warmers. Voir Hostname vérification.
2
Nommez le warmer et laissez-le inactif
Configurez d'abord, activez lorsque vous êtes satisfait.
3
Ajouter un ou plusieurs points de terminaison
Chaque point de terminaison possède une URL et une méthode HTTP, et éventuellement une étiquette, un corps et un type de contenu.
4
Ajoutez une authentification si le point de terminaison en a besoin
Les en-têtes globaux et les cookies sont appliqués à chaque demande effectuée par le warmer.
5
Développez éventuellement avec une matrice de configuration
Couvrez de nombreuses variantes (locales, locataires, identifiants) sans créer des dizaines de warmers presque identiques.
6
Réglez le rythme et les intervalles, puis activez
Même idée que le site Web warmers : réchauffez-le assez souvent pour battre le TTL de votre cache, assez lentement pour ne pas faire de mal.

Points de terminaison

Chaque point de terminaison du warmer est configuré indépendamment :

Étiquette: Un nom facultatif lisible par l’homme, afin qu’une longue liste de points de terminaison reste lisible.
URL: L'adresse complète du point de terminaison sur un hostname vérifié. Peut contenir des espaces réservés de chemin tels que {id} ou :id lorsqu'ils sont associés à une dimension PATH.
Méthode: GET, POST et autres selon votre forfait. Les forfaits autorisent généralement GET et HEAD par défaut, avec plus de méthodes sur les niveaux supérieurs.
Protocole: REST ou GRAPHQL. Choisir GraphQL révèle les champs d'opération et de requête.
Modèle de corps de demande: Le corps à envoyer, pour les méthodes qui en portent un. Nécessite le droit du corps de la requête API.
Type de contenu: Le type de contenu du corps de la requête, généralement application/json.
Purger → réchauffer: Marque le point de terminaison comme étant sûr à appeler deux fois, permettant ainsi la double récupération froid/chaud qui mesure l’amélioration. L'activer uniquement lorsque vous appelez deux fois n'a véritablement aucun effet secondaire.
Activé: Indique si ce point de terminaison spécifique est inclus dans les exécutions. Pratique pour désactiver temporairement un point de terminaison sans le supprimer.

Soyez prudent en marquant les opérations d'écriture idempotentes

Une double récupération sur un point de terminaison qui crée des commandes, envoie des e-mails ou débite des cartes le fera deux fois. Ne marquez un point final idempotent que lorsque le répéter est véritablement inoffensif.

Matrices de configuration

La plupart des API ont des variantes : le même point de terminaison appelé par paramètres régionaux, par locataire, par devise ou par ID. Créer un warmer pour chacun n'est pas maintenable.

Une matrice de configuration résout ce problème. Vous définissez des dimensions avec plusieurs valeurs et Cache Rocket étend le produit cartésien complet en requêtes chaleureuses individuelles.

Type de dimension	Injecte des valeurs dans	Exemple
`QUERY`	La chaîne de requête	`locale=en`, `locale=nl`, `locale=de`
`HEADER`	Un en-tête de requête	`X-Tenant: acme`, `X-Tenant: globex`
`COOKIE`	Un biscuit	`currency=EUR`, `currency=USD`
`PATH`	Un `{placeholder}` dans l'URL	`{id}` → `1`, `2`, `3`

Un exemple concret

text

Endpoint:  GET https://api.example.com/v1/products/{category}

Dimensions:
  PATH   category = shoes, bags, hats
  QUERY  locale   = en, nl

Expands to 6 warm requests:
  /v1/products/shoes?locale=en
  /v1/products/shoes?locale=nl
  /v1/products/bags?locale=en
  /v1/products/bags?locale=nl
  /v1/products/hats?locale=en
  /v1/products/hats?locale=nl

Les combinaisons se multiplient rapidement

Le nombre total de demandes est le produit du nombre de valeurs de chaque dimension. Trois dimensions de cinq valeurs chacune correspondent à 125 combinaisons à partir d'un seul point final. Le formulaire affiche un décompte courant et le maximum de votre plan : surveillez-le lorsque vous ajoutez des valeurs.

Si vous dépassez le maximum du plan, le warmer ne sera pas sauvegardé. Réduisez les valeurs, répartissez-les sur plusieurs warmers ou mettez à niveau.

Authentification

Les en-têtes de requête globaux et les cookies sont appliqués à chaque variante générée par le warmer. C'est là que va un en-tête Authorization ou un cookie de session.

En-têtes d'authentification typiques

text

Authorization: Bearer YOUR_LONG_LIVED_TOKEN
X-Api-Key: YOUR_API_KEY

Réchauffez la variante que les vrais clients demandent réellement

Si votre cache varie de Authorization, le réchauffement avec un jeton de service remplit une entrée de cache liée à ce jeton – qu'aucun client réel n'atteindra jamais. Pour les réponses partagées et pouvant être mises en cache, chauffez de la même manière qu’un client ordinaire appelle le point de terminaison.

Les jetons expirent. Si une API warmer commence soudainement à renvoyer 401, un jeton codé en dur est la première chose à vérifier.

GraphQL

GraphQL nécessite son propre traitement car les performances dépendent de l'opération spécifique, et non du chemin du point de terminaison. Appuyer une fois sur /graphql ne vous dit rien ; réchauffer vos trois requêtes les plus lourdes vous dit tout.

Définissez le protocole d'un point de terminaison sur GraphQL, puis fournissez :

Opération GraphQL — qu'il s'agisse d'un query ou d'un mutation. Le réchauffement des mutations n’est presque jamais approprié.
GraphQL requête — le document d'opération à envoyer.
Variables : fournissez-les via le modèle de corps de la demande ou sous forme de valeurs de dimension matricielle pour réchauffer plusieurs ensembles de variables.

Note

Le réchauffement GraphQL est contrôlé par son propre droit au plan, en plus de l'API warmers.

Importation OpenAPI

Sur les forfaits pris en charge, vous pouvez importer des points de terminaison directement à partir d'une spécification OpenAPI 3 au lieu de les saisir. Collez l'URL d'une spécification JSON ou YAML et cliquez sur Importer ; les points de terminaison découverts sont ajoutés au warmer, prêts à être élagués et ajustés.

Tip

L'importation apporte tout ce que décrit la spécification, y compris les opérations d'écriture. Examinez attentivement la liste et désactivez tout ce qui ne doit pas être appelé selon un calendrier avant de l'activer.

Limites et planification

Chauffage maximum par minute: Plafond de débit pour cette API warmer, équivalent au maximum d'URL par minute sur un site Web warmer.
Expiration du délai de demande: Combien de temps attendre une réponse avant d'abandonner.
Intervalle de démarrage automatique: Fréquence à laquelle commence un nouveau passage à chaud, en secondes.
Intervalle de mise en file d'attente: Rythme des travaux remis en file d'attente au sein du cycle.
Réécrire en HTTPS: Mettez à niveau les URL de point de terminaison http:// vers https://.
Horaire chaleureux: Fenêtres de pointe et heures creuses, même format JSON que le site web warmers. Voir Réchauffement avancé.

Votre plan limite également le nombre d'API warmers, de points de terminaison par warmer et de combinaisons par warmer.

Problèmes courants

Tout renvoie 401 ou 403.: L'en-tête ou le cookie d'authentification est manquant, erroné ou expiré. Les jetons à longue durée de vie sont le coupable habituel : vérifiez que le jeton est toujours valide et n'a pas tourné.
Le warmer ne sera pas sauvegardé, citant trop de combinaisons.: Votre matrice s'étend au-delà du maximum du plan. Réduisez les valeurs de dimension, divisez les points de terminaison en plusieurs warmers ou effectuez une mise à niveau.
La méthode dont j'ai besoin ne figure pas dans la liste déroulante.: Les forfaits limitent les méthodes HTTP autorisées. Les niveaux inférieurs autorisent généralement uniquement GET et HEAD.
Le réchauffement se déroule correctement mais les réponses sont encore lentes pour les vrais clients.: Vous remplissez probablement une variante de cache différente de celle demandée par les clients – généralement à cause d'un en-tête Authorization, d'un cookie ou d'un en-tête sur lequel votre CDN varie. Comparez la demande exacte qu'un vrai client envoie avec ce que le warmer envoie.
Puis-je réchauffer un point de terminaison qui nécessite un jeton signé de courte durée ?: Pas fiable, car le warmer ne peut pas générer une nouvelle signature par exécution. Soit vous exposez une variante non authentifiée pouvant être mise en cache, soit vous utilisez un jeton de service de longue durée là où il est sûr.