Come integrare il monitoraggio uptime nella tua app con un'API

Quando gestisci più di una manciata di siti, cliccare in una dashboard per aggiungere domini, controllare lo stato e tirare fuori report non scala più. Hai bisogno di un'API. Un'API di monitoraggio uptime ti permette di automatizzare la gestione dei domini, integrare i dati di monitoraggio nei tuoi strumenti e costruire workflow che rispondono agli incidenti in modo programmatico.

Questa guida illustra l'integrazione della REST API di Nova Uptime nella tua applicazione, dall'autenticazione e dagli endpoint principali agli esempi pratici di codice e ai pattern di integrazione.

Perché integrare il monitoraggio via API#

Automazione#

Aggiungere un nuovo dominio al monitoraggio non dovrebbe richiedere il login a una dashboard. Se la tua piattaforma fa il provisioning di siti web (per clienti, tenant o team interni), la configurazione del monitoraggio dovrebbe far parte dello script di provisioning. Quando un dominio viene dismesso, il monitoraggio dovrebbe essere rimosso automaticamente.

Dashboard custom#

Potresti già avere una dashboard interna o un portale clienti. Invece di chiedere agli utenti di controllare uno strumento di monitoraggio separato, porta i dati di uptime nell'interfaccia che usano già. Mostra la percentuale di uptime, gli incidenti recenti e lo stato attuale direttamente nella tua applicazione.

Integrazione CI/CD#

Dopo aver distribuito una nuova versione della tua applicazione, vuoi sapere immediatamente se il deployment ha rotto qualcosa. Un'integrazione API può controllare lo stato del monitoraggio dopo il deployment, recuperare gli incidenti recenti e segnalare eventuali problemi post-deploy nella tua pipeline CI/CD.

SaaS multi-tenant#

Se gestisci una piattaforma SaaS dove ogni cliente ha il proprio sottodominio o dominio custom, hai bisogno di monitoraggio su scala. L'API ti permette di aggiungere programmaticamente il monitoraggio per ogni nuovo cliente, rimuoverlo quando fa churn e tirare fuori metriche di uptime per cliente per la dashboard del loro account.

Panoramica dell'API Nova Uptime#

Base URL#

Tutte le richieste API vanno a:

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

Autenticazione#

Ogni richiesta deve includere una API key nell'header X-API-Key. Puoi generare una API key dalla dashboard Nova Uptime sotto Settings.

X-API-Key: your_api_key_here

Le API key sono stringhe alfanumeriche di 20 caratteri, uniche per ogni utente. Ogni chiave ha gli stessi permessi dell'account utente a cui appartiene.

Rate limit#

L'API impone rate limit per prevenire abusi. I limiti standard permettono un numero generoso di richieste al minuto per le operazioni normali. Se superi il rate limit, ricevi una risposta 429 Too Many Requests. Implementa il backoff esponenziale nella tua integrazione per gestirlo con grazia.

Formato di risposta#

Tutte le risposte seguono una struttura JSON consistente:

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

Le risposte di errore includono un messaggio descrittivo:

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

I codici di stato HTTP seguono le convenzioni standard: 200 per successo, 201 per risorse create, 400 per errori di validazione, 401 per fallimenti di autenticazione, 404 per non trovato, e 429 per rate limiting.

Endpoint principali#

Lista dei domini monitorati#

Recupera tutti i domini nel tuo account con il loro stato attuale, dati di uptime e configurazione.

Richiesta:

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

Risposta (abbreviata):

{
  "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
    }
  }
}

L'endpoint supporta la paginazione con il parametro query ?page=1. La dimensione massima della pagina è 50 domini.

Ottieni dettagli del dominio#

Recupera informazioni dettagliate su un dominio specifico, inclusa la sua configurazione completa.

Richiesta:

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

Aggiungi un nuovo dominio#

Aggiungi un dominio al monitoraggio. Il sistema normalizza l'URL (aggiunge https:// se mancante), lo valida e inizia il monitoraggio immediatamente.

Richiesta:

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
  }'

Risposta:

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

Lo stato del dominio sarà inizialmente unknown. Il primo health check viene eseguito entro pochi secondi dall'aggiunta del dominio, dopodiché lo stato si aggiorna a up, down o degraded.

Nota: c'è un limite di 10 domini via API per account (si applicano i limiti del piano). Il check interval deve essere uguale o superiore all'intervallo minimo consentito dal tuo piano.

Elimina un dominio#

Rimuovi un dominio dal monitoraggio. Si tratta di una soft delete; il dominio viene disattivato ma i suoi dati storici sono preservati.

Richiesta:

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

Ottieni gli incidenti del dominio#

Recupera gli incidenti più recenti (eventi di downtime) per un dominio specifico.

Richiesta:

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

Risposta (abbreviata):

{
  "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"
    }
  ]
}

L'endpoint restituisce i 20 incidenti più recenti.

Ottieni la cronologia dei controlli#

Recupera i risultati storici degli health check per un dominio. Utile per costruire grafici dei tempi di risposta o calcolare metriche di uptime custom.

Richiesta:

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

Il parametro hours controlla quanto indietro guardare, con un massimo di 720 ore (30 giorni) e un massimo di 500 record per risposta.

Esegui un controllo email health#

Esegui un controllo email health su qualsiasi dominio. Controlla record MX, SPF, DKIM, DMARC e stato delle blacklist.

Richiesta:

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"
  }'

Aggiungi "fresh": true per bypassare la cache e forzare un lookup fresco:

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
  }'

La risposta include i punteggi per ogni categoria (MX, SPF, DKIM, DMARC, blacklist), un punteggio complessivo, un voto in lettera e raccomandazioni attuabili.

Esempi di codice in JavaScript / Node.js#

Configurare un client API#

Crea un client API riutilizzabile per gestire autenticazione, gestione errori e parsing delle risposte:

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;
}

Aggiungere un dominio#

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);

Listare tutti i domini con paginazione#

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;
}

Controllare gli incidenti recenti#

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`
      );
    }
  }
}

Eseguire un controllo email health#

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;
}

Pattern di integrazione comuni#

Aggiungere domini automaticamente al deploy#

Se la tua pipeline di deployment crea o configura siti web, aggiungi il monitoraggio come step post-deploy:

// 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}`);
  }
}

Questo pattern è particolarmente utile per piattaforme che fanno il provisioning di sottodomini per i clienti. Ogni nuovo cliente ottiene il monitoraggio automaticamente senza intervento manuale.

Verifica dello stato post-deploy#

Dopo il deployment, controlla se il sito risponde correttamente:

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;
}

Costruire una status dashboard custom#

Porta i dati di monitoraggio nella tua dashboard:

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;
}

Audit programmati di email health#

Esegui controlli di email health su tutti i tuoi domini secondo una pianificazione e segnala quelli che sono scesi sotto una soglia:

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;
}

Best practice#

Gestione degli errori#

Gestisci sempre gli errori API con grazia. Possono verificarsi timeout di rete, rate limit ed errori del server. Implementa la logica di retry con backoff esponenziale:

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));
    }
  }
}

Paginazione#

Non assumere mai che tutti i dati stiano in una singola risposta. Gestisci sempre la paginazione quando elenchi domini o recuperi cronologia:

• Controlla il valore pagination.totalPages nelle risposte di lista.
• Itera attraverso tutte le pagine per ottenere dati completi.
• Rispetta la dimensione massima della pagina (50 per i domini).

Caching#

Se stai mostrando dati di monitoraggio in una dashboard che si aggiorna frequentemente, fai cache delle risposte API dalla tua parte. I cambiamenti di stato dei domini si misurano in minuti, non secondi, quindi una cache di 60 secondi per i dati di stato e una cache di 5 minuti per i dati storici sono ragionevoli.

I dati di email health cambiano ancora meno frequentemente. Un TTL di cache di 1 ora è appropriato per i risultati di email health.

Consapevolezza dei rate limit#

Struttura la tua integrazione per minimizzare le chiamate API non necessarie:

• Fai cache delle risposte quando possibile.
• Usa parametri di paginazione per recuperare solo i dati che ti servono.
• Evita di fare polling dell'API in loop stretti. Invece, fai polling a intervalli appropriati per il tuo caso d'uso (ogni 1-5 minuti per lo stato, ogni ora o quotidianamente per email health).
• Quando controlli più domini, aggiungi un piccolo ritardo tra le richieste per evitare di colpire i rate limit.

Proteggi la tua API key#

• Conserva la tua API key in variabili d'ambiente, non nel codice sorgente.
• Non esporre la API key in JavaScript lato client. Tutte le chiamate API dovrebbero passare attraverso il tuo backend.
• Se sospetti che una chiave sia stata compromessa, rigenerala immediatamente dalle impostazioni della dashboard Nova Uptime.
• Usa un'API key separata per ogni ambiente (sviluppo, staging, produzione) se possibile.

Gestire la normalizzazione degli URL del dominio#

L'API normalizza gli URL quando aggiungi domini (aggiungendo https:// se mancante), ma anche la tua integrazione dovrebbe normalizzare prima di fare richieste per evitare di creare voci duplicate:

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

Requisiti di accesso all'API#

L'API di Nova Uptime è disponibile su tutti i piani, incluso il Free. La pagina pricing ha un confronto completo di cosa include ogni piano:

• Piano Free: 5 domini, accesso API, dashboard, email health.
• Piano Pro: accesso API con fino a 100 domini.
• Piano Agency: accesso API con fino a 1.000 domini e tutte le funzionalità.

Genera la tua API key dalla pagina Settings nella dashboard Nova Uptime. Il riferimento API completo, inclusi gli schemi request/response per ogni endpoint, è disponibile nella pagina di documentazione API.

Conclusione#

Un'integrazione API trasforma il monitoraggio da un'attività manuale basata su dashboard a un componente automatizzato e programmabile della tua infrastruttura. Sia che tu stia costruendo una piattaforma SaaS multi-tenant, gestendo un'agenzia con centinaia di siti clienti o automatizzando la tua pipeline di deployment, l'API è l'interfaccia che fa scalare il monitoraggio.

Inizia con le basi: aggiungi domini in modo programmatico e tira fuori i dati di stato. Poi costruisci verso pattern più avanzati come la verifica dello stato post-deploy, dashboard custom e audit programmati di email health.

Il riferimento API completo con playground interattivo è disponibile su api.novauptime.com/api-docs. Puoi anche esplorare il set di funzionalità completo di Nova Uptime nella pagina features.