API-Schnittstelle (Version 1.3)

Über die API-Schnittstelle können Sie auf serverstate.de automatisiert zugreifen und diverse Daten wie z.B. Überwachungsaufträge, Checks, Benachrichtigungen oder Empfänger-Informationen auslesen. Diese Seite enthält eine detaillierte Dokumentation der API-Schnittstelle.

Folgende API-Schnittstellen stehen zur Verfügung:
- Zugriff auf Checks
- Zugriff auf Benachrichtigungen
- Zugriff auf Empfänger-Informationen
- Zugriff auf Überwachungsaufträge
- Zugriff auf Überwachungs-Statistik pro Monat
- Zugriff auf Überwachungs-Statistik pro Tag

Bitte sagen Sie Bescheid, falls Sie auf Daten zugreifen wollen oder irgendwelche Funktionen benötigen, für welche zur Zeit keine API-Schnittstelle existiert. Wir werden versuchen, diese dann zu implementieren.

Zugriff auf Checks
API-Request:
http://serverstate.de/api/1/checks/?nickname=...&password=...&sensor_id=...&from=...&to=...&state=...

API-Request (Zugriff via Check-ID):
http://serverstate.de/api/1/checks/?nickname=...&password=...&check_id=...

Parameter   Beispiel   Beschreibung
nickname   mynickname   Benutzername des serverstate.de Accounts.
password   34819d7beeabb9260a5c854bc85b3e44   Passwort als MD5-Hash.
sensor_id   12345   ID des Überwachungsauftrags. Diese ID wird in der
Adress-Leiste Ihres Browsers angezeigt, wenn Sie z.B.
auf Überwachungsauftrag-Bearbeiten klicken.
from   05.09.2011   Checks ab dem hier definierten Datum ausgeben.
to   09.09.2011   Checks bis zu diesem Datum ausgegeben.
state   successful   Checks nur mit einem bestimmten Status selektieren.
Folgende Werte können ausgegeben werden: all, successful und failed
Dieser Parameter ist optional. Standardmäßig werden alle Checks selektiert.
check_id   12345   Check ID. Wenn dieser Parameter gesetzt ist, dann sind die Parameter sensor_id, from, to und state nicht erforderlich.

API-Response:
<?xml version='1.0' encoding='UTF-8'?>
<checks>
 <check>
  <id>...</id>
  <created>...</created>
  <successful_flag>...</successful_flag>
  <checkpoint>...</checkpoint>
  <response_time>...</response_time>
  <failure_reason>...</failure_reason>
  <applied_information>...</applied_information>
 </check>
</checks>

Parameter   Beispiel   Beschreibung
id   12345   Check ID
created   09.09.2011 18:35   Datum und Zeit, zu denen der Check erstellt wurde.
successful_flag   FALSE   Check-Status (TRUE oder FALSE). Wenn TRUE, dann war der Check erfolgreich.
checkpoint   Deutschland (78.46.25.193)   Überwachungsstandort, von welchem aus der Check durchgeführt wurde. Bei Server-Parameter-Überwachungsaufträgen wird keine Überwachungsstandort-Information übermittelt, da solche Checks immer von dem selben Standort durchgeführt werden.
response_time   834   Response-Zeit in ms. Bei Server-Parameter-Überwachungsaufträgen wird keine Response-Zeit übermittelt.
failure_reason   CONTENT CHECK FAILED   Bei fehlerhaften Checks die genaue Fehlerursache.
applied_information     In diesem Feld wird eine zusätzliche Check-Information erfasst, deren Format von dem Überwachungstyp abhängt:
  • Bei Überwachungsaufträgen vom Typ Ping wird die zulässige Paketverlustrate (welche im Überwachungsauftrag definiert ist), sowie die aktuell gemessene Paketverlustrate in Prozent erfasst. Zum Beispiel beträgt bei dem Wert '50|10' die zulässige Paketverlustrate 50 Prozent und die aktuelle 10 Prozent.
  • Bei Überwachungsaufträgen vom Typ Server Parameter werden genaue Parameter sowie deren Werte erfasst. Zum Beispiel sind bei dem Wert 'cpu_usage|65|GREATER THAN|95;free_disk_space|10|LESS THAN|5' zwei Parameter (cpu_usage sowie free_disk_space) erfasst. Bei dem Parameter cpu_usage beträge das aktuelle Messergebnis 65 Einheiten (z.B. Auslastung in Prozent). Sollte bei einem Check das aktuelle Messergebnis größer als (siehe Schlüsselwort GREATER THAN) 95 Einheiten sein, wird der Check als Ausfall gewertet. Bei free_disk_space funktioniert dies nach dem gleichen Prinzip. Folgende Vergleichsoperatoren stehen zur Verfügung: GREATER THAN, LESS THAN, EQUALS, NOT EQUALS

Zugriff auf Benachrichtigungen
API-Request:
http://serverstate.de/api/1/notifications/?nickname=...&password=...

Parameter   Beispiel   Beschreibung
nickname   mynickname   Benutzername des serverstate.de Accounts.
password   34819d7beeabb9260a5c854bc85b3e44   Passwort als MD5-Hash.

API-Response:
<?xml version='1.0' encoding='UTF-8'?>
<notifications>
 <notification>
  <id>...</id>
  <created>...</created>
  <receiver_name>...</receiver_name>
  <receiver_contact>...</receiver_contact>
  <successful_flag>...</successful_flag>
  <type>...</type>
  <message>...</message>
 </notification>
</notifications>

Parameter   Beispiel   Beschreibung
id   12345   ID der Benachrichtigung.
created   09.09.2011 18:35   Datum und Zeit, zu denen die Benachrichtigung erstellt wurde.
receiver_name   Max Mustermann   Empfängername.
receiver_contact   contact@example.com   E-Mail, Twitter-Account, Pushover-ID, Handy-Nr oder Script-URL.
successful_flag   TRUE   Versandstatus (TRUE oder FALSE) der Benachrichtigung. Wenn FALSE,
dann konnte die Benachrichtigung nicht versendet werden.
type   EMAIL   Versandart der Benachrichtigung (EMAIL, SMS, TWITTER, PUSHOVER oder SCRIPT CALL).
message   DOWN-Nachricht: ...   Inhalt der Benachrichtigung. Bei Benachrichtigungen vom Typ SCRIPT CALL wird kein Inhalt übermittelt.

Zugriff auf Empfänger-Information
API-Request:
http://serverstate.de/api/1/contacts/?nickname=...&password=...

Parameter   Beispiel   Beschreibung
nickname   mynickname   Benutzername des serverstate.de Accounts.
password   34819d7beeabb9260a5c854bc85b3e44   Passwort als MD5-Hash.

API-Response:
<?xml version='1.0' encoding='UTF-8'?>
<contacts>
 <contact>
  <id>...</id>
  <name>...</name>
  <notify_by_email_flag>...</notify_by_email_flag>
  <email>...</email>
  <notify_by_sms_flag>...</notify_by_sms_flag>
  <phone_number>...</phone_number>
  <notify_by_twitter_flag>...</notify_by_twitter_flag>
  <twitter_username>...</twitter_username>
  <notify_by_pushover_flag>...</notify_by_pushover_flag>
  <pushover_id>...</pushover_id>
  <notify_by_script_call_flag>...</notify_by_script_call_flag>
  <script_url>...</script_url>
  <script_secret_key>...</script_secret_key>
 </contact>
</contacts>

Parameter   Beispiel   Beschreibung
id   12345   Empfänger-ID.
name   Max Mustermann   Empfänger-Name.
notify_by_email_flag   TRUE   Benachrichtigung (TRUE oder FALSE) per E-Mail. Wenn TRUE,
dann wird der Empfänger per E-Mail benachrichtigt.
email   contact@example.com   E-Mail Adresse.
notify_by_sms_flag   TRUE   Benachrichtigung (TRUE oder FALSE) per SMS. Wenn TRUE,
dann wird der Empfänger per SMS benachrichtigt.
phone_number   004916312345   Handy-Nr für die SMS-Benachrichtigung.
notify_by_twitter_flag   TRUE   Benachrichtigung (TRUE oder FALSE) per Twitter. Wenn TRUE,
dann wird der Empfänger per Twitter benachrichtigt.
twitter_username   @my_twitter_account   Benutzername von dem Twitter-Account.
notify_by_pushover_flag   TRUE   Benachrichtigung (TRUE oder FALSE) via Pushover. Wenn TRUE,
dann wird der Empfänger via Pushover benachrichtigt.
pushover_id   xBEsu9SvCAy6fTbQwRF5ngx4oDydAK   Pushover-Benutzer-ID sowie eine optionale Device-Bezeichnung. Falls eine Device-Bezeichnung existiert, dann werden beide Werte mit einem Punkt getrennt.
notify_by_script_call_flag   TRUE   Benachrichtigung (TRUE oder FALSE) per Skriptaufruf. Wenn TRUE,
dann wird der Empfänger per Skriptaufruf benachrichtigt.
script_url   http://example.com/my_script.php?sensor={SENSOR_ID}   Script-URL, welche aufgerufen wird.
script_secret_key   0vjpLnNcqq   Geheimschlüssel für die Validierung des Skriptaufrufs.

Zugriff auf Überwachungsaufträge
API-Request:
http://serverstate.de/api/1/sensors/?nickname=...&password=...&sensor_id=...

Parameter   Beispiel   Beschreibung
nickname   mynickname   Benutzername des serverstate.de Accounts.
password   34819d7beeabb9260a5c854bc85b3e44   Passwort als MD5-Hash.
sensor_id   12345   ID des Überwachungsauftrags. Dieser Parameter ist optional.

API-Response:
<?xml version='1.0' encoding='UTF-8'?>
<sensors>
 <sensor>
  <id>...</id>
  <name>...</name>
  <address>...</address>
  <port>...</port>
  <type>...</type>
  <check_interval>...</check_interval>
  <notify_about_failure_rule>...</notify_about_failure_rule>
  <notify_about_uptime_flag>...</notify_about_uptime_flag>
  <enabled_flag>...</enabled_flag>
  <last_check_date>...</last_check_date>
  <failure_flag>...</failure_flag>
  <timeout>...</timeout>
  <notification>
   <contact>
    <id>...</id>
   </contact>
   <contact>
    <id>...</id>
   </contact>
  <notification>
 </sensor>
</sensors>

Parameter   Beispiel   Beschreibung
id   12345   ID des Überwachungsauftrags.
name   Mein Überwachungsauftrag   Name des Überwachungsauftrags.
address   example.com   IP-Adresse, Domain oder URL, welche überwacht wird.
port   80   Port-Nummer. Bei Ping-Überwachungsaufträgen wird keine Port-Nummer übermittelt.
type   HTTP   Überwachungstyp (HTTP, HTTPS, POP3, SMTP, IMAP, PING, FTP, CUSTOM PORT oder SERVER PARAMETER).
check_interval   1   Überwachungsintervall in Minuten.
notify_about_failure_rule   IMMEDIATE   Definition, ab wann beim Ausfall die Benachrichtigung versendet
wird (IMMEDIATE, 2 FAILURE, 3 FAILURE, 4 FAILURE oder 5 FAILURE).
notify_about_uptime_flag   TRUE   Benachrichtigen, wenn der Dienst wieder online ist (TRUE oder FALSE).
enabled_flag   TRUE   Status des Überwachungsauftrags (TRUE oder FALSE).
Wenn TRUE, dann ist der Überwachungsauftrag aktiv.
last_check_date   09.09.2011 18:35   Datum und Zeit, wann die letzte Überprüfung auf Verfügbarkeit durchgeführt wurde.
failure_flag   FALSE   Aktueller Ausfall-Status (TRUE oder FALSE).
Wenn TRUE, dann ist der Dienst nicht verfügbar.
timeout   10   Check-Timeout in Millisekunden. Bei Überwachungsaufträgen
vom Typ SERVER PARAMETER wird keine Timeout-Information übermittelt.
notification     Hier sind die jeweiligen Empfänger definiert.

Zugriff auf Überwachungs-Statistik pro Monat
API-Request:
http://serverstate.de/api/1/monthly_report/?nickname=...&password=...&sensor_id=...&month=...

Parameter   Beispiel   Beschreibung
nickname   mynickname   Benutzername des serverstate.de Accounts.
password   34819d7beeabb9260a5c854bc85b3e44   Passwort als MD5-Hash.
sensor_id   12345   ID des Überwachungsauftrags.
month   09.2011   Monats- und Jahres-Vorgabe, für welche die Statistik-Information angezeigt wird.

API-Response:
<?xml version='1.0' encoding='UTF-8'?>
<monthly_report>
 <month>...</month>
 <uptime_percent>...</uptime_percent>
 <response_time>...</response_time>
 <total_downtime>...</total_downtime>
 <avg_downtime>...</avg_downtime>
 <number_of_downtimes>...</number_of_downtimes>
</monthly_report>

Parameter   Beispiel   Beschreibung
month   09.2011   Monat und Jahr, auf welche sich die Statistik-Information bezieht.
uptime_percent   99.74   Uptime in Prozent.
response_time   298   Durchschnittliche Antwortzeit in Millisekunden. Bei Überwachungsaufträgen
vom Typ SERVER PARAMETER wird keine Antwortzeit-Information übermittelt.
total_downtime   121   Die gesamte Ausfallzeit in Minuten.
avg_downtime   11   Durchschnittliche Ausfallzeit in Minuten.
number_of_downtimes   11   Anzahl der Ausfälle.

Zugriff auf Überwachungs-Statistik pro Tag
API-Request:
http://serverstate.de/api/1/daily_report/?nickname=...&password=...&sensor_id=...&day=...

Parameter   Beispiel   Beschreibung
nickname   mynickname   Benutzername des serverstate.de Accounts.
password   34819d7beeabb9260a5c854bc85b3e44   Passwort als MD5-Hash.
sensor_id   12345   ID des Überwachungsauftrags.
day   01.09.2011   Tages-, Monats- und Jahres-Vorgabe, für welche die Statistik-Information angezeigt wird.

API-Response:
<?xml version='1.0' encoding='UTF-8'?>
<daily_report>
 <day>...</day>
 <uptime_percent>...</uptime_percent>
 <response_time>...</response_time>
 <details>
  <hourly_report>
   <hour>...</hour>
   <uptime_percent>...</uptime_percent>
   <response_time>...</response_time>
  </hourly_report>
 </details>
</daily_report>

Parameter   Beispiel   Beschreibung
day   01.09.2011   Tag, Monat und Jahr, auf welche sich die Statistik-Information bezieht.
uptime_percent   99.79   Uptime in Prozent.
response_time   273   Durchschnittliche Antwortzeit in Millisekunden. Bei Überwachungsaufträgen
vom Typ SERVER PARAMETER wird keine Antwortzeit-Information übermittelt.
details     Hier ist die Statistik-Information pro Stunde aufgelistet.

Mögliche Fehler
Wenn ein Fehler auftritt, dann können statt dem XML-Response u.g. Fehler-Tokens
ausgegeben werden. Diese Fehler können bei jeder API-Schnittstelle vorkommen.
 
Fehler-Token   Beschreibung
ERROR_INVALID_REQUEST   Request-Parameter sind fehlerhaft.
ERROR_INVALID_AUTH   Übergebene Autorisierungsdaten sind fehlerhaft.
© 2010 — 2017 Intelions OÜ
Folgen: Twitter | Facebook
Tour | Preise | Partnerprogramm | FAQ | API-Schnittstelle

Neuigkeiten | AGB | Kontakt | Impressum