API publique

/api/v1 est l'interface stable en lecture seule pour les frontends alternatifs, panneaux publics, thèmes Canvas et intégrations serveur. La lecture ne demande aucun jeton ; l'écriture n'est pas exposée. Cette documentation correspond au Worker 1.1.93 ; le manifest du déploiement cible fait foi.

Endpoints

Méthode	Chemin	Rôle	Limite de débit par défaut
GET	/api/v1	version, capacités, découverte des endpoints	politique publique
GET	/api/v1/manifest	alias du manifest	politique publique
GET	/api/v1/status	cibles, état courant, résumés, télémétrie	120/min/IP
GET	/api/v1/checks	historique de disponibilité d'une cible	120/min/IP
GET	/api/v1/metrics	historique de métriques d'un Agent	30/min/IP
GET	/api/v1/pings	historique des pings TCP Agent	30/min/IP
GET	/api/v1/latency	historique de latence externe	60/min/IP

Les limites sont des défauts de production et peuvent changer ; les clients ne doivent pas les traiter comme des cibles de concurrence. Une page d'état n'a besoin de rafraîchir que selon la période de cache.

Toutes les routes sont aussi couvertes par une limitation globale best-effort. Si le compteur est indisponible, les lectures publiques peuvent continuer à servir ; les clients doivent quand même reculer sur 429 et ne jamais supposer qu'une requête n'a pas été limitée.

Requêtes de base

export API_BASE='https://YOUR-API'
curl -fsSL "$API_BASE/api/v1"
curl -fsSL "$API_BASE/api/v1/status?days=30&lite=1"

const response = await fetch(`${apiBase}/api/v1/status?days=30&lite=1`, {
  method: 'GET',
  credentials: 'omit',
  headers: { accept: 'application/json' },
})

if (!response.ok) throw new Error(`HTTP ${response.status}`)
const status = await response.json()

CORS

L'intégration serveur n'est pas affectée par le CORS navigateur. Les frontends navigateur doivent ajouter leur origine exacte à DEVELOPER_API_ORIGINS :

DEVELOPER_API_ORIGINS = "https://status.example.com,http://localhost:5173"

Règles : origines complètes uniquement, sans chemin ni slash final ; HTTPS en production ; HTTP seulement pour les adresses de dev localhost ; * est ignoré ; la variable n'affecte que /api/v1, jamais les endpoints d'écriture admin ou Agent. L'origine du site configurée sur le Worker est ajoutée automatiquement. En cas d'absence, la réponse peut rester HTTP 200 mais Access-Control-Allow-Origin ne renverra pas l'origine demandée, donc les navigateurs bloquent les lectures de script.

Conventions de réponse

Les réponses de succès incluent ok: true ; les erreurs incluent généralement ok: false et error. Les clients doivent vérifier le statut HTTP et ok JSON. Les réponses v1 portent d'abord X-NIE-SLA-API-Version: v1 et conservent l'alias historique X-NStatus-API-Version. Les en-têtes cache/source suivent le même modèle sans changer la sémantique.

Cache et rafraîchissement

Les endpoints peuvent renvoyer Cache-Control, et status/historique peuvent toucher la Cloudflare Cache API. Respectez les en-têtes de cache ; ne polluez pas pour générer du trafic inutile. Recommandé pour les panneaux publics : rafraîchir l'état courant toutes les 20-60 s ; demander les graphiques seulement à l'ouverture des détails ou au changement de plage ; mettre en pause le polling quand la page est masquée ; ajouter un délai aléatoire après reprise réseau.

Règles de stabilité

Dans v1, le serveur peut ajouter des champs optionnels, des membres de tableaux et des drapeaux de capacité, mais ne supprimera ni ne renommera silencieusement des champs existants. Les clients doivent ignorer les champs inconnus et gérer null, les tableaux vides, l'historique manquant et les sources temporairement périmées.

Politique d'erreurs : Gestion des erreurs. Client réutilisable, polling, modèle d'état et conseils de graphiques : Intégration API.