ベストプラクティス

ポーリング頻度をプランに合わせる

各プランは決まった更新間隔で価格を配信します。Freeは毎日1回、Liteは30分、Standardは10分、AdvancedとProは60秒、UltraとBusinessは15秒、Enterpriseは5秒です。それより頻繁に/latestをリクエストしても同じ価格が返され、クォータを無駄に消費するだけです。

目安として、/latestはプランの更新間隔のあいだキャッシュし、過去の日のデータは無期限にキャッシュしてください。

複数のシンボルをまとめてリクエストする

1回のリクエストで任意の数のシンボルを取得でき、コストは1つのシンボルをリクエストする場合と変わりません。必要なものはすべて1回の呼び出しで取得してください：

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

10分に1回ポーリングすると月に約4,500リクエスト、1分に1回ポーリングすると約45,000リクエストを使用します。それに合わせてプランを選んでください。

自分の側でキャッシュする

APIの前段に小さなキャッシュを置くと、アプリの応答が速くなり、使用量も予測しやすくなります。リクエストが失敗した場合でも、最後に取得できた正常な価格を返し続けられます：

const TTL = 10 * 60 * 1000; // Standardプラン：10分ごとの更新
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; // 最後に取得できた正常な価格を返す
    throw new Error(`${data.error.code}: ${data.error.info}`);
  }
  cache = { at: Date.now(), data };
  return data;
}

ポーリングの代わりにストリームを使う

すべての更新を必要とするダッシュボードやトレーディングツールには、Proプラン以上で利用できる/streamを使ってください。長時間維持される1本のServer-Sent Events接続で、新しい価格が届きしだい配信されるため、ポーリングループを調整する必要がありません。

「金が4,000ドルを超えたら知らせる」のようなしきい値のロジックには価格アラートとWebhookを使えば、ポーリング自体が不要になります。

エラーを適切に処理する

• すべてのレスポンスでsuccessを確認し、error.codeで分岐してください。
• 104、500、503はバックオフ付きでリトライしてください。バリデーションエラーはリトライしないでください。
• APIに到達できない場合は、最後に取得できた正常な価格をタイムスタンプとともに表示し続けてください。
• X-RateLimit-Remainingヘッダーとシステムステータスページを監視してください。

詳細とコード例はエラーハンドリングをご覧ください。

連携を安全に保つ

• キーは環境変数またはシークレットマネージャーに保存し、Gitやクライアントサイドのバンドルには決して含めないでください。
• ブラウザからの呼び出しにはドメイン制限付きキーを使用してください。
• アプリケーションと環境ごとに1つのキーを使い、担当者が離れたときやキーが漏えいした可能性があるときはキーをローテーションしてください。
• すべてのWebhookでX-MetalAPI-Signatureヘッダーを検証し、古いタイムスタンプは拒否してください。

パフォーマンスのヒント

• HTTPクライアントを1つ使い回し、リクエスト間で接続が維持されるようにしてください。
• 圧縮されたレスポンス（gzipまたはbr）を受け付けるようにしてください。ほとんどのHTTPクライアントはデフォルトで対応しています。
• リクエストのタイムアウトを10秒程度に設定し、ネットワークが遅くてもアプリがブロックされないようにしてください。
• 起動時に/symbolsを一度読み込み、不正なシンボルでリクエストが失敗する前に、ユーザー入力をその一覧で検証してください。
• 監視ツールから/usageを呼び出し、クォータを使い切る前に警告を受け取れるようにしてください。この呼び出しは無料です。