%%site.help.doc.json-api%%

%%site.help.doc.json-api%%

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: gui.bloonix.de
Content-Type: application/json
Content-Length: 35

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

Dabei sind ein paar Dinge zu beachten.

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" : "starsky.bloonix.de",
    "status" : "ok",
    "data" : {
        "sid" : "sdfah7823fs83k3..."
    },
    "total" : 1,
    "size" : 1,
    "offset" : 0
}

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

server_time Die Uhrzeit des Servers, der die Daten ausgeliefert hat.
who_am_i Der Hostname des Servers, der die Daten ausgeliefert hat.
status Der Status der Anfrage. Diese kann entweder ok oder einen Fehlercode im Format err-NUMMER sein.
message Sollte der Status einer Anfrage nicht ok sein, dann finden Sie hier eine Fehlermeldung.
failed Sollten 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.
data Hier finden Sie die Daten zur Abfrage, wenn die Abfrage erfolgreich war und der Status ok ist.
total, size, offset Diese 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://gui.bloonix.de/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://gui.bloonix.de/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:

/hosts Liste aller Hosts abfragen.
/hosts/1000 Abfrage des Hosts mit der ID 1000.
/hosts/1000/services Alle Services des Hosts 1000 abfragen.
/hosts/1000/services/400 Abfrage des Service mit der ID 400.
/hosts/1000/services/400/update Den Service mit der ID 400 updaten.

Objekte abfragen, erstellen, updaten, löschen

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

/hosts Liste aller Hosts abfragen.
/hosts/options Abfrage der Parameter zum Erstellen eines Hosts.
/hosts/create Einen neuen Host anlegen.
/hosts/1000 Abfrage des Hosts mit der ID 1000.
/hosts/1000/options Abfrage des Parameter zum Updaten des Hosts mit der ID 1000.
/hosts/1000/update Den Host mit der ID 1000 updaten.
/hosts/1000/delete Den 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:

{
    "size" : 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:

{
    "size" : 3,
    "offset" : 3
}

Antwort:

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

Login und Logout

Route: /login
Parameter Datatype Default Required Description
username STRING (100)   yes Username
password STRING (100)   yes Password

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

Route: /hosts/:host_id/charts

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

{
    "server_time" : "1400514110002",
    "status" : "ok",
    "who_am_i" : "starsky.bloonix.de",
    "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_id Die ID des Service, für welchen die Chart-Daten abgerufen werden sollen.
chart_id Die ID des Charts. Jeder Service kann mehrere Charts haben.
preset Der Zeitrahmen der Daten. Der Wert 3h bedeuted: die letzten 3 Stunden. Folgende Voreinstellungen sind möglich: 3h, 6h, 12h, 18h, 1d, 3d, 5d, 7d
avg Mit 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" : "starsky.bloonix.de",
    "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://gui.bloonix.de/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 { "type" : "preset", "preset" : "2h" } 2h bedeuted ab jetzt plus 2 Stunden
absolute { "type" : "absolute", "begin" : "2014-10-10 10:00:00", "end" : "2014-10-11 10:00:00" } Einrichtung einer Downtime zu einer festen Uhrzeit
timeslice { "type" : "timeslice", "timeslice" : "Monday - Sunday 00:00 - 01:00" } Einrichtung einer wiederkehrenden Downtime.

Eine Beschreibung der einzelnen Zeitangaben finden Sie hier: %%site.help.doc.scheduled-downtimes%%

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

curl -H 'Content-Type: application/json' https://gui.bloonix.de/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://gui.bloonix.de/token/csrf -d '
{
    "sid" : "sid"
}'

curl -H 'Content-Type: application/json' https://gui.bloonix.de/hosts/delete-downtime/ -d '
{
    "sid" : "sid",
    "token" : "token",
    "host_id" : [60, 62, 96],
    "flag" : "backup"
}'