EN | DE

Die Bloonix JSON API

Allgemeines

Die gesamte WebGUI von Bloonix ist in JavaScript entwickelt. Die Daten werden über die JSON-API von Bloonix mittels HTTP-POST Abfragen im JSON-Format ausgetauscht. Aus diesem Grund ist es möglich, alle Komponenten und Objekte übers Web zu verwalten.

Sie finden in diesem Dokument nicht alle Komponenten, die abgefragt werden können. Sollten Sie Fragen haben, so wenden Sie sich bitte an den Bloonix-Support.

HTTP Abfrage

Eine Abfrage über die JSON-API sieht beispielhaft wie folgt aus:

POST /login HTTP/1.1
Host: demo.bloonix.org
Content-Type: application/json
Content-Length: 35

{"username":"your-user-name","password":"your-secret-password"}

Dabei sind ein paar Dinge zu beachten.

  • Die HTTP-Methode muss POST sein.
  • Der Content-Type muss 'application/json' sein.
  • Der JSON-String muss UTF-8 kodiert sein.

HTTP Antwort

Die Antwort der JSON-API erfolgt, wie auch die Anfrage, im JSON-Format. Dabei hat die Antwort beispielhaft folgenden strukturellen Aufbau:

{
    "server_time" : "1400501371624",
    "who_am_i" : "demo.bloonix.org",
    "status" : "ok",
    "data" : {
        "sid" : "sdfah7823fs83k3..."
    },
    "total" : 1,
    "size" : 1,
    "offset" : 0
}

Folgende Werte können in der Antwort der JSON-API vorkommen:

server_timeDie Uhrzeit des Servers, der die Daten ausgeliefert hat.
who_am_iDer Hostname des Servers, der die Daten ausgeliefert hat.
statusDer Status der Anfrage. Diese kann entweder ok oder einen Fehlercode im Format err-NUMMER sein.
messageSollte der Status einer Anfrage nicht ok sein, dann finden Sie hier eine Fehlermeldung.
failedSollten Sie Formulardaten zum Anlegen oder zur Modifizierung von Objekten senden und der Status der Antwort nicht ok sein, dann finden Sie hier wohlmöglich die Parameter, welche nicht valide Angaben enthalten.
dataHier finden Sie die Daten zur Abfrage, wenn die Abfrage erfolgreich war und der Status ok ist.
total, size, offsetDiese Angaben sind immer dann wichtig, wenn Sie eine Liste von Daten abfragen. Wenn Sie zum Beispiel eine Liste von Hosts abfragen, erhalten Sie in der Antwort immer die Information, wieviele Daten (total) tatsächlich vorhanden sind; wieviele Elemente das Datenarrray enthält (size) und wo die Liste beginnt (offset). Diese Angaben sind auch mit OFFSET und LIMIT von SQL-Abrfagen vergleichbar.

Grundlegender Aufbau von Routen

Was sind Routen?

Eine Route ist schlichtweg der Pfad einer URL. Die gesamte JSON-API von Bloonix wird über Routen angesteuert. Wenn Sie zum Beispiel eine Liste aller Hosts abfragen möchten, so geschieht das über die Route /hosts. Wenn Sie nun die Daten eines bestimmten Hosts abfragen möchten, so wird an die Route noch die ID des Hosts angehängt, etwa so /hosts/1000.

Sie können das auch gerne einmal testen. Rufen Sie dazu in der URL-Leiste Ihres Browsers folgende URL auf:

https://demo.bloonix.org/hosts

Sie erhalten dann eine Liste aller Hosts im JSON-Format. Mit dem Parameter pretty können Sie der JSON-API mitteilen, dass die Ausgabe etwas leserlicher ausgegeben werden soll.

https://demo.bloonix.org/hosts?pretty

Aufbau von Routen

Der Aufbau der Routen ist einheitlich strukturiert. Schauen wir uns doch beispielhaft folgende Route etwas genauer an:

/hosts/1000/services/400/update

Mit dieser Route wird die Konfiguration eines Service geupdated und zwar der Service, der die ID 400 hat und zum Host mit der ID 1000 gehört. Schauen wir uns als nächstes die Teilpfade an und welche Ausgabe mit jedem Teilpfad zu erwarten ist:

/hostsListe aller Hosts abfragen.
/hosts/1000Abfrage des Hosts mit der ID 1000.
/hosts/1000/servicesAlle Services des Hosts 1000 abfragen.
/hosts/1000/services/400Abfrage des Service mit der ID 400.
/hosts/1000/services/400/updateDen Service mit der ID 400 updaten.

Objekte abfragen, erstellen, updaten, löschen

Es folgt eine Übersicht über den allgemeinen Aufbau von Routen.

/hostsListe aller Hosts abfragen.
/hosts/optionsAbfrage der Parameter zum Erstellen eines Hosts.
/hosts/createEinen neuen Host anlegen.
/hosts/1000Abfrage des Hosts mit der ID 1000.
/hosts/1000/optionsAbfrage des Parameter zum Updaten des Hosts mit der ID 1000.
/hosts/1000/updateDen Host mit der ID 1000 updaten.
/hosts/1000/deleteDen Host mit der ID 1000 löschen.

Grundlegendes zu Abfragen von Listen

Beispielrouten

Route: /hosts
Route: /services
Route: /contacts

Listen werden immer in Teilen ausgeliefert. Das heißt, wenn es 10000 Hosts gibt, werden doch nur 50 Hosts in einer Antwort geliefert. Dies gilt zur Vorbeugung von zu hoher Speicherauslastung. Die Anzahl der Objekte pro Abfrage kann mit bestimmten POST-Parametern kontrolliert werden.

Beispiel einer Anfrage mit folgenden POST-Daten:

{
    "limit" : 3,
    "offset" : 0
}

Antwort:

{
    "status" : "ok",
    "data" : [
        { "id" : 1 },
        { "id" : 2 },
        { "id" : 3 }
    ],
    "total" : 10000,
    "size" : 3,
    "offset" : 0
}

Die Antwort enthält wie angefordert nur drei Objeke. Um die nächsten drei Objekte abzufragen, muss eine weitere Abfrage gesendet werden. Der offset muss dabei erhöht werden:

{
    "limit" : 3,
    "offset" : 3
}

Antwort:

{
    "status" : "ok",
    "data" : [
        { "id" : 4 },
        { "id" : 5 },
        { "id" : 6 }
    ],
    "total" : 10000,
    "size" : 3,
    "offset" : 3
}

Login und Logout

Route: /login
ParameterDatatypeDefaultRequiredDescription
usernameSTRING (100)yesUsername
passwordSTRING (100)yesPassword

Antwort:

{
    "status" : "ok",
    "data" : {
        "sid" : "a-very-long-session-id"
    }
}

Die Session-ID muss für jede weitere Abfrage verwendet werden. Setzen Sie die Session-ID daher mit Namen sid als Cookie im HTTP-Header jedes Abfrage.

Route: /logout

Verwenden Sie diese Route um sich auszuloggen.

Objekte erstellen, ändern und löschen

Grundlegendes

Für alle Aktionen, bei denen Sie Objekte erstellen, ändern oder löschen möchten, ist ein sogenanntes CSRF-Token notwendig. Nur mit diesem Token dürfen Objekte modifiziert werden. Bevor Sie also ein Objekt modifizieren möchten, fordern Sie zunächst ein Token an. Die Route lautet hierzu wie folgt:

Route: /token/csrf

Die Antwort enthält das Token:

{
   "status" : "ok",
   "data" : "37746962038f0a430c55d3c8d49eb5585b1dac1456ec393cfda9295a9578a5bf",
}

Dieses Token müssen Sie mit dem Parameter token zu den POST-Daten hinzufügen.

Bitte beachten Sie, dass das Token nur für 30 Sekunden gültig ist. Sollten Sie versuchen, ein Objekt ohne ein Token zu modifizieren oder sollte die Gültigkeitsdauer eines Tokens abgelaufen sein, so erhalten Sie eine Fehlermeldung.

Objekte erstellen und ändern

In diesem Dokument sind die einzelnen Parameter zum Erstellen oder zum Ändern von Objekten bewußt nicht dokumentiert. Stattdessen können Sie die Parameter über die JSON-API abfragen.

Angenommen, Sie möchten einen neuen Host erstellen und sich hierzu die Parameter anschauen. Unter folgender Route können Sie die Parameter mit den möglichen Optionen abrufen:

/hosts/options

Falls Sie die Parameter eines Hosts abrufen möchten, der bereits angelegt ist, dann können Sie das über folgende Route:

/hosts/:host_id/options

Wobei Sie den Platzhalter :host_id einfach mit der ID des Hosts ersetzen.

Auf diese Weise können Sie für alle Objekte die Parameter abfragen, die zum Erstellen oder zum Ändern erforderlich sind.

Objekte - Benutzer

Routen

Route: /administration/users
Route: /administration/users/options
Route: /administration/users/create
Route: /administration/users/:user_id
Route: /administration/users/:user_id/update
Route: /administration/users/:user_id/delete

Objekte - Benutzergruppen

Routen

Route: /administration/groups
Route: /administration/groups/options
Route: /administration/groups/create
Route: /administration/groups/:group_id
Route: /administration/groups/:group_id/update
Route: /administration/groups/:group_id/delete
Route: /administration/groups/:group_id/hosts/list
Route: /administration/groups/:group_id/hosts/list-non
Route: /administration/groups/:group_id/hosts/add
Route: /administration/groups/:group_id/hosts/remove
Route: /administration/groups/:group_id/users/list
Route: /administration/groups/:group_id/users/list-non
Route: /administration/groups/:group_id/users/add
Route: /administration/groups/:group_id/users/remove

Objekte - Kontakte

Routen

Route: /contacts
Route: /contacts/options
Route: /contacts/create
Route: /contacts/:contact_id
Route: /contacts/:contact_id/update
Route: /contacts/:contact_id/delete

Objekte - Kontaktgruppen

Routen

Route: /contactgroups
Route: /contactgroups/options
Route: /contactgroups/create
Route: /contactgroups/:contactgroup_id
Route: /contactgroups/:contactgroup_id/update
Route: /contactgroups/:contactgroup_id/delete
Route: /contactgroups/:contactgroup_id/contacts/in-group
Route: /contactgroups/:contactgroup_id/contacts/not-in-group
Route: /contactgroups/:contactgroup_id/contacts/add
Route: /contactgroups/:contactgroup_id/contacts/remove
Route: /contactgroups/:contactgroup_id/hosts/in-group
Route: /contactgroups/:contactgroup_id/hosts/not-in-group
Route: /contactgroups/:contactgroup_id/hosts/add
Route: /contactgroups/:contactgroup_id/hosts/remove
Route: /contactgroups/:contactgroup_id/services/in-group
Route: /contactgroups/:contactgroup_id/services/not-in-group
Route: /contactgroups/:contactgroup_id/services/add
Route: /contactgroups/:contactgroup_id/services/remove

Objekte - Hosts

Routen

Route: /hosts
Route: /hosts/options
Route: /hosts/create
Route: /hosts/:host_id
Route: /hosts/:host_id/update
Route: /hosts/:host_id/delete

Objekte - Templates

Routen

Route: /templates/hosts
Route: /templates/hosts/options
Route: /templates/hosts/create
Route: /templates/hosts/:template_id
Route: /templates/hosts/:template_id/update
Route: /templates/hosts/:template_id/delete

Objekte - Timeperiods

Routen

Route: /timeperiods
Route: /timeperiods/options
Route: /timeperiods/create
Route: /timeperiods/:timperiod_id
Route: /timeperiods/:timperiod_id/update
Route: /timeperiods/:timperiod_id/delete
Route: /timeperiods/:timperiod_id/timeslices
Route: /timeperiods/:timperiod_id/timeslices/create
Route: /timeperiods/:timperiod_id/timeslices/:timeslice_id
Route: /timeperiods/:timperiod_id/timeslices/:timeslice_id/update
Route: /timeperiods/:timperiod_id/timeslices/:timeslice_id/delete

Chart Daten

Mit dieser Abfrage werden alle verfügbaren Chart-Daten eines Hosts gezeigt. Beispiel:

Route: /hosts/:host_id/charts
{
    "server_time" : "1400514110002",
    "status" : "ok",
    "who_am_i" : "demo.bloonix.org",
    "data" : [
        {
            "plugin" : "Apache2.Statistics",
            "options" : {
                "chart-type" : "area",
                "ylabel" : "workers",
                "series" : [
                    {
                        "color" : "#ff7a0d",
                        "name" : "busyworkers"
                    },
                    {
                        "color" : "#005467",
                        "name" : "idleworker"
                    }
                ]
            },
            "host_id" : "60",
            "chart_id" : "215",
            "hostname" : "test1.bloonix.de",
            "service_id" : "149",
            "subkeys" : "",
            "service_name" : "Apache2 process status",
            "title" : "Apache - workers",
            "ipaddr" : "127.0.0.1"
        }
    ],
    "total" : "10",
    "size" : 1,
    "offset" : 0
}
Route: /hosts/charts/data

Um nun die Daten eines Charts abzurufen, ist folgende Abfrage notwendig:

{
    "service_id" : "149",
    "chart_id" : "215",
    "preset" : "3h",
    "avg" : "600p"
}

Die einzelnen Parameter haben folgende Bedeutung:

service_idDie ID des Service, für welchen die Chart-Daten abgerufen werden sollen.
chart_idDie ID des Charts. Jeder Service kann mehrere Charts haben.
presetDer Zeitrahmen der Daten. Der Wert 3h bedeuted: die letzten 3 Stunden. Folgende Voreinstellungen sind möglich: 3h, 6h, 12h, 18h, 1d, 3d, 5d, 7d
avgMit diesem Parameter wird bestimmt, auf wieviele Datenpunkte die Daten runter berechnet werden sollen. Weitere Informationen finden Sie hierzu weiter unten.

Der Parameter avg

Der Parameter avg ist ein sehr nützlicher, aber auch wichtiger Parameter.

Angenommen, Sie möchten einen Chart mit einer Weite von 800 Pixel erzeugen. In diesem Chart könnte man 800 Datenpunkte unterbringen - ein Datenpunkt pro Pixel -, ohne das sich Datenpunkte überschreiben würden. Wenn man nun Chart-Daten aus den letzten 3 Tagen anfordert, dann kommen da ca. 4320 Datenpunkte zusammen (pro Minute ein Datenpunkt bei einem Check-Intervall von 60 Sekunden).

Um diese Datenpunkte nun optimal im Chart anzuzeigen, kann man über den Parameter avg mitteilen, wieviele Datenpunte maximal benötigt werden. Sprich, bei einer Weite von 800 Pixel würde man der Wert von avg auf 800p setzen.

Was nun passiert ist, dass aus 4320 Datenpunkten 800 Datenpunkte berechnet werden. Dabei werden jede 6 Datenpunkte (4320 / 800 aufgerundet) zusammengefasst und ein Durchschnitt berechnet. Bei der Zusammenfassung der Datenpunte wird der Zeitstempel des ersten Datenpunkts verwendet. Auf diese Weise wird die Datenmenge auf ca. 720 Datenpunkte gesenkt.

Chart Daten

Die Struktur der Chart-Daten sieht wie folgt aus:

{
    "server_time" : "1400516771622",
    "status" : "ok",
    "who_am_i" : "demo.bloonix.org",
    "data" : {
        "stats" : {
             "sendrep" : [
                [
                    1400506030000,
                    1
                ],
                [
                    1400516747000,
                    250
                ]
            ]
        },
        "service" : {
             "options" : {
                "chart-type" : "area",
                "ylabel" : "workers",
                "series" : [
                    {
                        "color" : "#ff7a0d",
                        "name" : "busyworkers"
                    },
                    {
                        "color" : "#005467",
                        "name" : "idleworker"
                    }
                ]
            },
            "host_id" : "60",
            "service_id" : "149",
            "chart_id" : "215",
            "hostname" : "test1.bloonix.de",
            "service_name" : "Apache2 process status",
            "category" : "System,Webserver,Apache2",
            "ipaddr" : "127.0.0.1",
            "plugin" : "Apache2.Statistics",
            "description" : "Apache2 webserver statistics and process status.",
            "title" : "Apache - workers"
        }
    }
}

Die Chart-Daten selbst finden Sie im Baum unter data/stats/key. Der erste Wert ist immer der UNIX-Timestamp in Millisekunden und der zweite Wert ist der Wert des Statistik-Keys, welcher in diesem Beispiel sendrep ist.

Beschreibung der Statistiken

Route: /plugin-stats/:plugin

Im obigen Beispiel sind die Chart-Daten des Plugins Apache2.Statistics abgerufen worden. Wenn Sie nun eine detaillierte Beschreibung der einzelnen Statistik-Keys benötigen, so können Sie diese über folgende die Abfrage /plugin-stats/Apache2.Statistics erhalten.

Host Downtimes einrichten (Kurzbeschreibung)

Dies ist eine Kurzbeschreibung um eine Downtime für mehrere Hosts einzurichten und wieder zu löschen. Die Hosts werden mit dem Schlüssel host_id angegeben. Wichtig ist, dass Sie den Parameter flag setzen. Anhand dieses Flags können Downtimes eindeutig identifiziert und später wieder gelöscht werden.

Einloggen

curl -H 'Content-Type: application/json' https://demo.bloonix.org/login/ -d '
{
    "username" : "username",
    "password" : "password"
}'

Die Session-ID aus sid muss für alle weiteren Requests verwendet werden.

Token abfragen und Downtimes einrichten

Das Token aus data muss für den Request zum Anlegen der Downtimes verwendet werden. Das Token ist nur für 30 Sekunden gültig.

Zur Angabe der Dauer der Downtime gibt es drei Typen: preset, absolute und timeslice

preset (2h bedeuted ab jetzt plus 2 Stunden)

bc. {
"type" : "preset",
"preset" : "2h"
}

absolute (Einrichtung einer Downtime zu einer festen Uhrzeit)

{
    "type" : "absolute",
    "begin" : "2014-10-10 10:00:00",
    "end" : "2014-10-11 10:00:00"
}

timeslice (Einrichtung einer wiederkehrenden Downtime.)

{
    "type" : "timeslice",
    "timeslice" : "Monday - Sunday 00:00 - 01:00"
}

Eine Beschreibung der einzelnen Zeitangaben finden Sie hier: Geplante Wartungsarbeiten einrichten

curl -H 'Content-Type: application/json' https://demo.bloonix.org/token/csrf -d '
{
    "sid" : "sid"
}'

curl -H 'Content-Type: application/json' https://demo.bloonix.org/hosts/create-downtime/ -d '
{
    "sid" : "sid",
    "token" : "token",
    "host_id" : [60, 62, 96],
    "description" : "Test",
    "timezone" : "Europe/Berlin",
    "preset" : "2h",
    "type" : "preset",
    "flag" : "backup"
}'

Token abfragen und Downtimes löschen

Das Token aus data muss für den Request zum Löschen der Downtimes verwendet werden. Das Token ist nur für 30 Sekunden gültig.

curl -H 'Content-Type: application/json' https://demo.bloonix.org/token/csrf -d '
{
    "sid" : "sid"
}'

curl -H 'Content-Type: application/json' https://demo.bloonix.org/hosts/delete-downtime/ -d '
{
    "sid" : "sid",
    "token" : "token",
    "host_id" : [60, 62, 96],
    "flag" : "backup"
}'
Über Bloonix - Über Bloonix | Über Bloonix - Lizenzen | Über Bloonix - Wie funktioniert Bloonix | Über Bloonix - Feature Liste | Über Bloonix - Plugins | Über Bloonix - Systemanforderungen | Sicherheit - Allgemein | Sicherheit - Agent und Satellit | Installation - Wichtige Information vorab | Installation - Repositories | Installation - Elasticsearch | Installation - PostgreSQL | Installation - MySQL/MariaDB | Installation - Nginx | Installation - Bloonix-WebGUI | Installation - Bloonix-Server | Installation - Bloonix-Plugins | Installation - Bloonix-Agent | Installation - Bloonix-WTRM | Installation - Manuelle Installation | Installation - Quick Guide für CentOS 7 und PostgreSQL | Installation - Quick Guide für CentOS 7 und MariaDB | Installation - Quick Guide für Debian 8 und MariaDB | Konfiguration - Allgemeines | Konfiguration - Bloonix-WebGUI | Konfiguration - Bloonix-Server | Konfiguration - Bloonix-Service-Checker | Konfiguration - Bloonix-Agent | Konfiguration - Skripte und Cronjobs | HowTos - Plugins entwickeln | HowTos - Coding mit Stil | HowTos - Dokumentation auf Bloonix.org | HowTos - Verteilte Überwachung mit dem Bloonix-Satelliten | HowTos - Automatische Registrierung von Hosts | FAQ - Wie überwacht Bloonix Hosts und Services | WebGUI - Die Bloonix-WebGUI | WebGUI - Commpanies und wie diese funktionieren | WebGUI - Einen neuen Host anlegen | WebGUI - Host Parameter im Detail | WebGUI - Host Variablen | WebGUI - Host Templates | WebGUI - Klassen von Hosts | WebGUI - Einen neuen Service anlegen | WebGUI - Service Parameter im Detail | WebGUI - Host-Alive-Checks | WebGUI - Web-Transactions | WebGUI - Abhängigkeiten | WebGUI - Geplante Wartungsarbeiten | WebGUI - Kontakte und Benachrichtigungen | WebGUI - Benutzer- und Gruppenverwaltung | WebGUI - Eigene Charts erstellen | WebGUI - Notification Screen | WebGUI - Die Bloonix JSON API | WebGUI - Den Bloonix-Agenten installieren | WebGUI - Den Bloonix-Agenten konfigurieren