APIを使ってアプリにアップタイムモニタリングを組み込む方法

少数を超えるウェブサイトを管理し始めると、ダッシュボードをクリックしてドメインを追加し、ステータスを確認し、レポートを取得する作業はスケールしなくなります。そこで必要になるのがAPIです。アップタイムモニタリングAPIを使えば、ドメイン管理を自動化し、監視データを自社ツールに統合し、インシデントへプログラム的に対応するワークフローを構築できます。

このガイドでは、Nova UptimeのREST APIをアプリケーションに統合する方法を、認証や主要エンドポイントから実践的なコード例、統合パターンまで順を追って解説します。

なぜAPIで監視を統合するのか#

自動化

新しいドメインを監視に追加するためにダッシュボードへログインする必要はないはずです。プラットフォームが(クライアント、テナント、社内チーム向けに)ウェブサイトをプロビジョニングしているなら、監視のセットアップもプロビジョニングスクリプトの一部であるべきです。ドメインが廃止されたら、監視も自動的に解除されるべきです。

カスタムダッシュボード

すでに社内ダッシュボードやクライアントポータルをお持ちの場合があります。ユーザーに別の監視ツールを確認してもらうのではなく、彼らがすでに使っているインターフェースに稼働率データを取り込みましょう。アップタイムの割合、最近のインシデント、現在のステータスをアプリケーション内で直接表示できます。

CI/CD統合#

新しいバージョンのアプリケーションをデプロイした直後に、何かが壊れていないかをすぐに知りたいはずです。API統合により、デプロイ後に監視ステータスを確認し、最近のインシデントを取得し、CI/CDパイプライン内でデプロイ後の問題をフラグ付けできます。

マルチテナントSaaS#

各顧客が独自のサブドメインやカスタムドメインを持つSaaSプラットフォームを運営している場合、大規模な監視が必要です。APIを使えば、新規顧客ごとに監視をプログラム的に追加し、解約時には削除し、顧客ごとのアップタイム指標をアカウントダッシュボードに取得できます。

Nova Uptime APIの概要#

ベースURL#

すべてのAPIリクエストは次の宛先に送信します。

https://api.novauptime.com/api/v1

認証

すべてのリクエストには、X-API-KeyヘッダーにAPIキーを含める必要があります。APIキーはNova UptimeダッシュボードのSettings(設定)から生成できます。

X-API-Key: your_api_key_here

APIキーは20文字の英数字文字列で、ユーザーごとに一意です。各キーは、それが属するユーザーアカウントと同じ権限を持ちます。

レート制限

APIは不正利用を防ぐためにレート制限を設けています。標準の制限では通常運用に十分な分あたりリクエスト数を許容します。レート制限を超えると、429 Too Many Requestsのレスポンスが返ります。これに優雅に対応するため、統合側で指数バックオフを実装してください。

レスポンス形式

すべてのレスポンスは一貫したJSON構造に従います。

{
  "success": true,
  "message": "Domains retrieved successfully",
  "data": {
    // Response payload
  }
}

エラーレスポンスには説明的なメッセージが含まれます。

{
  "success": false,
  "message": "Domain not found"
}

HTTPステータスコードは標準的な慣例に従います。成功は200、リソース作成は201、バリデーションエラーは400、認証失敗は401、未検出は404、レート制限は429です。

主要エンドポイント

監視中ドメインの一覧取得

アカウント内のすべてのドメインを、現在のステータス、稼働率データ、設定情報とともに取得します。

リクエスト:

curl -X GET "https://api.novauptime.com/api/v1/domains" \
  -H "X-API-Key: your_api_key_here"

レスポンス(抜粋):

{
  "success": true,
  "data": {
    "domains": [
      {
        "id": "clx1abc...",
        "url": "https://example.com",
        "status": "up",
        "lastCheckedAt": "2026-02-04T10:30:00Z",
        "responseTime": 245,
        "uptimePercentage": 99.97,
        "sslValid": true,
        "sslExpiresAt": "2026-08-15T00:00:00Z",
        "checkInterval": 300,
        "emailHealthGrade": "A"
      }
    ],
    "pagination": {
      "page": 1,
      "totalPages": 3,
      "total": 28
    }
  }
}

このエンドポイントは?page=1クエリパラメータによるページネーションをサポートします。最大ページサイズは50ドメインです。

ドメイン詳細の取得

特定ドメインに関する詳細情報を、完全な設定とともに取得します。

リクエスト:

curl -X GET "https://api.novauptime.com/api/v1/domains/clx1abc123" \
  -H "X-API-Key: your_api_key_here"

新しいドメインの追加

ドメインを監視に追加します。システムはURLを正規化し(必要ならhttps://を付与)、検証してから即座に監視を開始します。

リクエスト:

curl -X POST "https://api.novauptime.com/api/v1/domains" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://newsite.example.com",
    "checkInterval": 300
  }'

レスポンス:

{
  "success": true,
  "message": "Domain added successfully",
  "data": {
    "id": "clx2def...",
    "url": "https://newsite.example.com",
    "status": "unknown",
    "checkInterval": 300
  }
}

ドメインのステータスは初期状態でunknownになります。最初のヘルスチェックはドメイン追加から数秒以内に実行され、その後ステータスはup、down、またはdegradedに更新されます。

注意: APIによるドメイン追加はアカウントあたり10件までという制限があります(プランの制限が適用されます)。チェック間隔は、お使いのプランで許可される最小値以上である必要があります。

ドメインの削除

ドメインを監視から削除します。これはソフトデリートであり、ドメインは無効化されますが、過去のデータは保持されます。

リクエスト:

curl -X DELETE "https://api.novauptime.com/api/v1/domains/clx2def456" \
  -H "X-API-Key: your_api_key_here"

ドメインインシデントの取得

特定ドメインの直近のインシデント(ダウンタイムイベント)を取得します。

リクエスト:

curl -X GET "https://api.novauptime.com/api/v1/domains/clx1abc123/incidents" \
  -H "X-API-Key: your_api_key_here"

レスポンス(抜粋):

{
  "success": true,
  "data": [
    {
      "id": "inc_001",
      "startedAt": "2026-02-03T14:22:00Z",
      "resolvedAt": "2026-02-03T14:25:30Z",
      "durationSeconds": 210,
      "httpStatus": 503,
      "screenshotUrl": "https://api.novauptime.com/screenshots/inc_001.jpg"
    }
  ]
}

このエンドポイントは直近20件のインシデントを返します。

チェック履歴の取得

ドメインの過去のヘルスチェック結果を取得します。応答時間グラフの作成や、独自のアップタイム指標の算出に便利です。

リクエスト:

curl -X GET "https://api.novauptime.com/api/v1/domains/clx1abc123/history?hours=24" \
  -H "X-API-Key: your_api_key_here"

hoursパラメータでさかのぼる範囲を制御します。最大720時間(30日)、レスポンスあたり最大500件です。

メール配信ヘルスチェックの実行

任意のドメインに対してメール配信ヘルスチェックを実行します。MXレコード、SPF、DKIM、DMARC、ブラックリストの状態を確認します。

リクエスト:

curl -X POST "https://api.novauptime.com/api/v1/email-health" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com"
  }'

キャッシュをバイパスして強制的に新規取得するには、"fresh": trueを追加します。

curl -X POST "https://api.novauptime.com/api/v1/email-health" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "fresh": true
  }'

レスポンスには各カテゴリ(MX、SPF、DKIM、DMARC、ブラックリスト)のスコア、総合スコア、文字グレード、実行可能な推奨事項が含まれます。

JavaScript / Node.jsのコード例#

APIクライアントのセットアップ#

認証、エラー処理、レスポンス解析を扱う再利用可能なAPIクライアントを作成します。

const API_BASE = 'https://api.novauptime.com/api/v1';
const API_KEY = process.env.Nova Uptime_API_KEY;

async function apiRequest(method, path, body = null) {
  const options = {
    method,
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
  };

  if (body) {
    options.body = JSON.stringify(body);
  }

  const response = await fetch(`${API_BASE}${path}`, options);
  const json = await response.json();

  if (!json.success) {
    throw new Error(json.message || `API error: ${response.status}`);
  }

  return json.data;
}

ドメインの追加

async function addDomainToMonitoring(url, checkInterval = 300) {
  const data = await apiRequest('POST', '/domains', {
    url,
    checkInterval,
  });

  console.log(`Domain added: ${data.id}`);
  return data;
}

// Usage
await addDomainToMonitoring('https://mysite.example.com', 60);

ページネーションを使った全ドメインの一覧取得

async function getAllDomains() {
  const allDomains = [];
  let page = 1;
  let totalPages = 1;

  while (page <= totalPages) {
    const data = await apiRequest('GET', `/domains?page=${page}`);
    allDomains.push(...data.domains);
    totalPages = data.pagination.totalPages;
    page++;
  }

  return allDomains;
}

直近インシデントの確認

async function getRecentIncidents(domainId) {
  const incidents = await apiRequest(
    'GET',
    `/domains/${domainId}/incidents`
  );
  return incidents;
}

// Check if any domain has had incidents in the last hour
async function checkAllDomainsForRecentIssues() {
  const domains = await getAllDomains();
  const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);

  for (const domain of domains) {
    const incidents = await getRecentIncidents(domain.id);
    const recentIncidents = incidents.filter(
      (inc) => new Date(inc.startedAt) > oneHourAgo
    );

    if (recentIncidents.length > 0) {
      console.log(
        `${domain.url}: ${recentIncidents.length} incident(s) in the last hour`
      );
    }
  }
}

メール配信ヘルスチェックの実行

async function checkEmailHealth(domain) {
  const result = await apiRequest('POST', '/email-health', {
    domain,
    fresh: true,
  });

  console.log(`${domain}: Grade ${result.grade} (${result.score}/100)`);

  if (result.recommendations) {
    const critical = result.recommendations.filter(
      (r) => r.severity === 'critical'
    );
    if (critical.length > 0) {
      console.log(`  Critical issues: ${critical.length}`);
      critical.forEach((r) => console.log(`  - ${r.message}`));
    }
  }

  return result;
}

一般的な統合パターン

デプロイ時のドメイン自動追加

デプロイパイプラインがウェブサイトを作成または構成している場合、デプロイ後のステップとして監視を追加します。

// In your deployment script or CI/CD pipeline
async function postDeployMonitoring(deployedUrl) {
  try {
    // Check if domain is already monitored
    const domains = await getAllDomains();
    const existing = domains.find((d) => d.url === deployedUrl);

    if (!existing) {
      await addDomainToMonitoring(deployedUrl, 300);
      console.log(`Monitoring added for ${deployedUrl}`);
    } else {
      console.log(`${deployedUrl} already monitored (ID: ${existing.id})`);
    }
  } catch (error) {
    // Monitoring failure should not block deployment
    console.error(`Failed to set up monitoring: ${error.message}`);
  }
}

このパターンは、顧客サブドメインをプロビジョニングするプラットフォームで特に役立ちます。新規顧客ごとに、手動操作なしで監視が自動的に追加されます。

デプロイ後のヘルス確認

デプロイ後、サイトが正しく応答しているかを確認します。

async function verifyPostDeploy(domainId, waitMinutes = 3) {
  // Wait for a few check cycles to complete
  console.log(`Waiting ${waitMinutes} minutes for health checks...`);
  await new Promise((resolve) =>
    setTimeout(resolve, waitMinutes * 60 * 1000)
  );

  // Check for incidents since the deploy started
  const incidents = await getRecentIncidents(domainId);
  const deployTime = new Date(Date.now() - waitMinutes * 60 * 1000);

  const postDeployIncidents = incidents.filter(
    (inc) => new Date(inc.startedAt) > deployTime
  );

  if (postDeployIncidents.length > 0) {
    console.error('Post-deploy incidents detected:');
    postDeployIncidents.forEach((inc) => {
      console.error(
        `  HTTP ${inc.httpStatus} at ${inc.startedAt}`
      );
    });
    return false;
  }

  console.log('No post-deploy incidents. Deployment looks healthy.');
  return true;
}

カスタムステータスダッシュボードの構築

監視データを自社ダッシュボードに取り込みます。

async function getStatusDashboardData() {
  const domains = await getAllDomains();

  const dashboard = {
    total: domains.length,
    up: domains.filter((d) => d.status === 'up').length,
    down: domains.filter((d) => d.status === 'down').length,
    degraded: domains.filter((d) => d.status === 'degraded').length,
    averageResponseTime:
      domains.reduce((sum, d) => sum + (d.responseTime || 0), 0) /
      domains.length,
    sslExpiringSoon: domains.filter((d) => {
      if (!d.sslExpiresAt) return false;
      const daysLeft =
        (new Date(d.sslExpiresAt) - Date.now()) / (1000 * 60 * 60 * 24);
      return daysLeft < 30;
    }),
    domains: domains.map((d) => ({
      url: d.url,
      status: d.status,
      responseTime: d.responseTime,
      uptime: d.uptimePercentage,
      emailGrade: d.emailHealthGrade,
    })),
  };

  return dashboard;
}

定期実行のメール配信ヘルス監査

すべてのドメインに対して定期的にメール配信ヘルスチェックを実行し、しきい値を下回ったものをフラグ付けします。

async function weeklyEmailHealthAudit() {
  const domains = await getAllDomains();

  const results = [];
  for (const domain of domains) {
    try {
      // Extract just the domain name from the URL
      const domainName = new URL(domain.url).hostname;
      const health = await checkEmailHealth(domainName);
      results.push({
        domain: domainName,
        score: health.score,
        grade: health.grade,
      });

      // Add a small delay between requests to respect rate limits
      await new Promise((resolve) => setTimeout(resolve, 1000));
    } catch (error) {
      results.push({
        domain: domain.url,
        score: null,
        grade: 'Error',
        error: error.message,
      });
    }
  }

  // Flag domains scoring below 70
  const flagged = results.filter((r) => r.score !== null && r.score < 70);
  if (flagged.length > 0) {
    console.log('Domains with email health issues:');
    flagged.forEach((r) => {
      console.log(`  ${r.domain}: ${r.grade} (${r.score}/100)`);
    });
  }

  return results;
}

ベストプラクティス

エラー処理

APIエラーは常に優雅に処理してください。ネットワークタイムアウト、レート制限、サーバーエラーが発生する可能性があります。指数バックオフを伴うリトライロジックを実装します。

async function apiRequestWithRetry(method, path, body = null, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiRequest(method, path, body);
    } catch (error) {
      if (attempt === maxRetries) throw error;

      // Exponential backoff: 1s, 2s, 4s
      const delay = Math.pow(2, attempt - 1) * 1000;
      console.log(
        `Attempt ${attempt} failed. Retrying in ${delay}ms...`
      );
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

ページネーション

すべてのデータが単一のレスポンスに収まると仮定してはいけません。ドメインの一覧取得や履歴の取得時には、必ずページネーションを処理してください。

• 一覧レスポンスのpagination.totalPages値を確認します。
• すべてのページを反復して完全なデータを取得します。
• 最大ページサイズ(ドメインは50)を尊重します。

キャッシュ

頻繁に更新されるダッシュボードに監視データを表示している場合、APIレスポンスは自分の側でキャッシュしましょう。ドメインステータスの変化は秒ではなく分単位で測定されるため、ステータスデータには60秒のキャッシュ、履歴データには5分のキャッシュが妥当です。

メール配信ヘルスデータの変化はさらに緩やかです。メール配信ヘルスの結果には1時間のTTLキャッシュが適切です。

レート制限への配慮

不要なAPI呼び出しを最小化するように統合を構成してください。

• 可能なときはレスポンスをキャッシュします。
• ページネーションパラメータを使って必要なデータだけを取得します。
• タイトなループでAPIをポーリングしないでください。代わりに、用途に応じた間隔(ステータスは1〜5分ごと、メール配信ヘルスは時間または日単位)でポーリングしてください。
• 複数ドメインを確認する際は、レート制限に引っかからないよう各リクエスト間に小さな遅延を挟みます。

APIキーの安全な管理#

• APIキーはソースコードではなく環境変数に保存してください。
• クライアントサイドのJavaScriptにAPIキーを露出させないでください。すべてのAPI呼び出しはバックエンド経由で行うべきです。
• キーが漏洩した疑いがあれば、Nova Uptimeダッシュボードの設定から直ちに再生成してください。
• 可能であれば、環境ごと(開発、ステージング、本番)に別々のAPIキーを使ってください。

ドメインURLの正規化を扱う#

APIはドメイン追加時にURLを正規化します(必要ならhttps://を付与)が、重複エントリの作成を避けるため、リクエスト前に統合側でも正規化することをおすすめします。

function normalizeUrl(url) {
  if (!url.startsWith('http://') && !url.startsWith('https://')) {
    url = 'https://' + url;
  }
  // Remove trailing slash
  return url.replace(/\/+$/, '');
}

APIアクセスの要件#

Nova UptimeのAPIはFreeを含むすべてのプランで利用できます。各プランに含まれる内容の比較は料金ページをご覧ください。

• Freeプラン: ドメイン5件、APIアクセス、ダッシュボード、メール配信ヘルス。
• Proプラン: APIアクセス、最大100ドメイン。
• Agencyプラン: APIアクセス、最大1,000ドメイン、すべての機能。

APIキーはNova UptimeダッシュボードのSettingsページから生成できます。各エンドポイントのリクエスト/レスポンススキーマを含む完全なAPIリファレンスはAPIドキュメントページにあります。

まとめ

API統合は、監視を手動でダッシュボードに依存する作業から、インフラの自動化されたプログラム可能なコンポーネントへと変えてくれます。マルチテナントSaaSプラットフォームを構築している場合でも、何百ものクライアントサイトを管理するエージェンシーを運営している場合でも、デプロイパイプラインを自動化している場合でも、APIは監視をスケールさせるためのインターフェースです。

まずは基本から始めましょう。プログラム的にドメインを追加し、ステータスデータを取得します。そこからデプロイ後のヘルス確認、カスタムダッシュボード、定期実行のメール配信ヘルス監査といった、より高度なパターンへと発展させていきましょう。

インタラクティブなプレイグラウンド付きの完全なAPIリファレンスはapi.novauptime.com/api-docsで公開しています。Nova Uptimeの全機能は機能ページでもご紹介しています。