En İyi Uygulamalar

Sorgulama sıklığınızı planınıza göre ayarlayın

Her plan fiyatları sabit bir güncelleme aralığında sunar: Free planda günlük, Lite'ta 30 dakika, Standard'da 10 dakika, Advanced ve Pro'da 60 saniye, Ultra ve Business'ta 15 saniye, Enterprise'da ise 5 saniye. /latest endpoint'ini bundan daha sık çağırmak aynı fiyatları döndürür ve kotanızı boşa harcar.

Genel bir kural olarak, /latest yanıtlarını planınızın güncelleme aralığı boyunca, geçmiş günlere ait verileri ise süresiz olarak önbelleğe alın.

Birçok sembolü tek seferde isteyin

Tek bir istek istediğiniz sayıda sembol döndürebilir ve tek bir sembol için yapılan istekle aynı maliyete sahiptir. İhtiyacınız olan her şeyi tek bir çağrıda isteyin:

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

10 dakikada bir sorgulamak ayda yaklaşık 4.500 istek, dakikada bir sorgulamak ise yaklaşık 45.000 istek gerektirir. Planınızı buna göre seçin.

Kendi tarafınızda önbelleğe alın

API'nin önüne koyacağınız küçük bir önbellek, uygulamanızı hızlı ve kullanımınızı öngörülebilir tutar. Ayrıca bir istek başarısız olursa son geçerli fiyatları sunmaya devam etmenizi sağlar:

const TTL = 10 * 60 * 1000; // Standard plan: 10 dakikalık güncellemeler
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; // son geçerli fiyatları sun
    throw new Error(`${data.error.code}: ${data.error.info}`);
  }
  cache = { at: Date.now(), data };
  return data;
}

Sorgulamak yerine akışı kullanın

Her güncellemeye ihtiyaç duyan gösterge panelleri ve alım satım araçları için Pro ve üzeri planlarda /stream kullanın. Uzun ömürlü tek bir Server-Sent Events bağlantısı, yeni fiyatları geldikleri anda iletir; ayarlamanız gereken bir sorgulama döngüsü yoktur.

“Altın 4.000 doları geçtiğinde bana haber ver” gibi eşik mantıkları için fiyat alarmlarını ve webhook'ları kullanın ve sorgulamayı tamamen bırakın.

Hataları zarif şekilde ele alın

• Her yanıtta success alanını kontrol edin ve error.code değerine göre dallanın.
• 104, 500 ve 503 hatalarını geri çekilmeyle (backoff) yeniden deneyin. Doğrulama hatalarını yeniden denemeyin.
• API'ye ulaşılamıyorsa son geçerli fiyatı zaman damgasıyla birlikte göstermeye devam edin.
• X-RateLimit-Remaining header'ını ve sistem durumu sayfasını takip edin.

Ayrıntılar ve kod örnekleri Hata yönetimi rehberindedir.

Entegrasyonunuzu güvende tutun

• Anahtarları ortam değişkenlerinde veya bir gizli bilgi yöneticisinde (secrets manager) saklayın; asla Git'te ya da istemci tarafı paketlerde (bundle) tutmayın.
• Tarayıcıdan yapılan tüm çağrılar için alan adıyla sınırlandırılmış anahtarlar kullanın.
• Her uygulama ve ortam için ayrı bir anahtar kullanın; ekipten biri ayrıldığında veya bir anahtarın sızmış olma ihtimali olduğunda anahtarları yenileyin.
• Her webhook'un X-MetalAPI-Signature header'ını doğrulayın ve eski zaman damgalarını reddedin.

Performans ipuçları

• Bağlantıların istekler arasında açık kalması için tek bir HTTP istemcisini yeniden kullanın.
• Sıkıştırılmış yanıtları (gzip veya br) kabul edin. Çoğu HTTP istemcisi bunu varsayılan olarak yapar.
• Yavaş bir ağın uygulamanızı asla kilitlememesi için yaklaşık 10 saniyelik bir istek zaman aşımı belirleyin.
• /symbols listesini başlangıçta bir kez yükleyin ve hatalı sembollerin istekleri başarısız kılmasına izin vermek yerine kullanıcı girdisini bu listeye göre doğrulayın.
• Kotanız bitmeden sizi uyarması için izleme sisteminizden /usage endpoint'ini çağırın. Ücretsizdir.