Bonnes pratiques

Adapter la fréquence d'interrogation à votre plan

Chaque plan fournit des prix à un intervalle de mise à jour fixe : une fois par jour sur Free, 30 minutes sur Lite, 10 minutes sur Standard, 60 secondes sur Advanced et Pro, 15 secondes sur Ultra et Business, et 5 secondes sur Enterprise. Demander /latest plus souvent renvoie les mêmes prix et consomme du quota pour rien.

En règle générale, mettez /latest en cache pendant l'intervalle de mise à jour de votre plan et conservez indéfiniment les données des jours passés.

Demander plusieurs symboles à la fois

Une requête peut renvoyer autant de symboles que vous le souhaitez et coûte autant qu'une requête pour un seul symbole. Demandez tout ce dont vous avez besoin en un seul appel :

GET /api/v1/latest?api_key=YOUR_API_KEY&currencies=XAU,XAG,XPT,XPD,EUR,GBP

Interroger l'API toutes les 10 minutes représente environ 4 500 requêtes par mois, et toutes les minutes environ 45 000. Choisissez votre plan en conséquence.

Mettre en cache de votre côté

Un petit cache devant l'API garde votre application rapide et votre consommation prévisible. Il vous permet aussi de continuer à servir les derniers prix valides si une requête échoue :

const TTL = 10 * 60 * 1000; // Plan Standard : mises à jour toutes les 10 minutes
let cache = { at: 0, data: null };

export async function getPrices() {
  if (cache.data && Date.now() - cache.at < TTL) return cache.data;

  const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG,XPT,XPD", {
    headers: { "X-API-Key": process.env.METALAPI_KEY },
  });
  const data = await res.json();

  if (!data.success) {
    if (cache.data) return cache.data; // servir les derniers prix valides
    throw new Error(`${data.error.code}: ${data.error.info}`);
  }
  cache = { at: Date.now(), data };
  return data;
}

Le streaming plutôt que le polling

Pour les tableaux de bord et les outils de trading qui ont besoin de chaque mise à jour, utilisez /stream à partir du plan Pro. Une seule connexion Server-Sent Events de longue durée transmet les nouveaux prix dès leur arrivée, sans boucle de polling à régler.

Pour une logique de seuil du type « préviens-moi quand l'or dépasse 4 000 $ », utilisez les alertes de prix et webhooks et passez-vous complètement de polling.

Gérer les erreurs proprement

• Vérifiez success sur chaque réponse et basez votre logique sur error.code.
• Relancez 104, 500 et 503 avec un backoff. Ne relancez pas les erreurs de validation.
• Si l'API est injoignable, continuez d'afficher le dernier prix valide avec son horodatage.
• Surveillez l'en-tête X-RateLimit-Remaining et la page d'état du système.

Les détails et le code se trouvent dans Gestion des erreurs.

Sécuriser votre intégration

• Stockez les clés dans des variables d'environnement ou un gestionnaire de secrets, jamais dans Git ni dans des bundles côté client.
• Utilisez des clés restreintes par domaine pour tout appel depuis le navigateur.
• Utilisez une clé par application et par environnement, et renouvelez les clés lorsqu'une personne quitte l'équipe ou qu'une clé a pu fuiter.
• Vérifiez l'en-tête X-MetalAPI-Signature de chaque webhook et rejetez les horodatages trop anciens.

Conseils de performance

• Réutilisez un même client HTTP afin que les connexions restent ouvertes entre les requêtes.
• Acceptez les réponses compressées (gzip ou br). La plupart des clients HTTP le font par défaut.
• Définissez un délai d'expiration d'environ 10 secondes par requête, pour qu'un réseau lent ne bloque jamais votre application.
• Chargez /symbols une fois au démarrage et validez les saisies des utilisateurs à partir de cette liste, plutôt que de laisser des symboles invalides faire échouer vos requêtes.
• Appelez /usage depuis votre supervision pour être averti avant d'épuiser votre quota. C'est gratuit.