Öffentliche API

/api/v1 ist das stabile Nur-Lese-Interface für alternative Frontends, öffentliche Panels, Canvas-Themes und Serverintegrationen. Lesen braucht kein Token; Schreiben wird nicht exponiert. Diese Dokumentation entspricht Worker 1.1.93; das Manifest des Ziel-Deployments ist maßgeblich.

Endpoints

Methode	Pfad	Zweck	Standard-Rate-Limit
GET	/api/v1	Version, Fähigkeiten, Endpoint-Erkennung	öffentliche Policy
GET	/api/v1/manifest	Alias des Manifests	öffentliche Policy
GET	/api/v1/status	Ziele, aktueller Zustand, Zusammenfassungen, Telemetrie	120/min/IP
GET	/api/v1/checks	Verfügbarkeitshistorie eines Ziels	120/min/IP
GET	/api/v1/metrics	Metrikhistorie eines Agents	30/min/IP
GET	/api/v1/pings	Agent-TCP-Ping-Historie	30/min/IP
GET	/api/v1/latency	externe Latenzhistorie	60/min/IP

Limits sind Produktionsstandards und können sich ändern; Clients sollten sie nicht als Konkurrenzziele behandeln. Eine Statusseite muss nur pro Cache-Periode aktualisieren.

Alle Routen sind zusätzlich durch best-effort globales Rate-Limiting abgedeckt. Ist der Zähler nicht verfügbar, können öffentliche Lesezugriffe weiter bedient werden; Clients sollten trotzdem auf 429 zurückweichen und nie annehmen, eine Anfrage sei nicht limitiert gewesen.

Basis-Anfragen

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

Serverintegration ist vom Browser-CORS nicht betroffen. Browser-Frontends müssen ihre exakte Origin zu DEVELOPER_API_ORIGINS hinzufügen:

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

Regeln: nur vollständige Origins, ohne Pfad oder abschließenden Slash; HTTPS in Produktion; HTTP nur für lokale Dev-Adressen; * wird ignoriert; die Variable betrifft nur /api/v1, nie Admin- oder Agent-Schreibendpoints. Die konfigurierte Site-Origin des Workers wird automatisch ergänzt. Bei einem Fehltreffer kann die Antwort weiterhin HTTP 200 sein, aber Access-Control-Allow-Origin spiegelt die angefragte Origin nicht, also blockieren Browser Skript-Lesevorgänge.

Antwortkonventionen

Erfolgsantworten enthalten ok: true; Fehler enthalten meist ok: false und error. Clients müssen HTTP-Status und JSON-ok prüfen (Latency-Kompatibilitätsfehler können HTTP 200 verwenden). v1-Antworten tragen primär X-NIE-SLA-API-Version: v1; der alte Alias X-NStatus-API-Version bleibt kompatibel. Cache-/Source-Header folgen demselben Muster, ohne die Semantik zu ändern.

Cache und Aktualisierung

Endpoints können Cache-Control liefern, und Status/Historie können die Cloudflare Cache API treffen. Cache-Header respektieren; nicht pollen, um sinnlosen Traffic zu erzeugen. Empfohlen für öffentliche Panels: aktuellen Zustand alle 20-60 s aktualisieren; Charts nur beim Öffnen der Details oder bei Bereichswechsel anfordern; Polling bei versteckter Seite pausieren; nach Netzwiederherstellung zufälligen Delay ergänzen.

Stabilitätsregeln

Innerhalb von v1 darf der Server optionale Felder, Array-Mitglieder und Fähigkeits-Flags hinzufügen, vorhandene Felder aber nie stillschweigend löschen oder umbenennen. Clients müssen unbekannte Felder ignorieren und null, leere Arrays, fehlende Historie und vorübergehend veraltete Quellen behandeln.

Fehler-Policy: Fehlerbehandlung. Wiederverwendbarer Client, Polling, Zustandsmodell und Chart-Hinweise: API-Integration.