API-Schnittstelle (Version 1.4)

Ü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:
https://serverstate.de/api/1/checks/?nickname=...&password=...&sensor_id=...&from=...&to=...&state=...

API-Request (Zugriff via Check-ID):
https://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:
https://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, Script-URL oder Telegram Chat-ID.
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, SCRIPT CALL oder TELEGRAM).
message DOWN-Nachricht: ... Inhalt der Benachrichtigung. Bei Benachrichtigungen vom Typ SCRIPT CALL wird kein Inhalt übermittelt.

Zugriff auf Empfänger-Information

API-Request:
https://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>
  <notify_by_telegram_flag>...</notify_by_telegram_flag>
  <telegram_chat_id>...</telegram_chat_id>
 </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.
notify_by_telegram_flag TRUE Benachrichtigung (TRUE oder FALSE) per Telegram. Wenn TRUE,
dann wird der Empfänger per Telegram benachrichtigt.
telegram_chat_id 12345 Telegram Chat-ID.

Zugriff auf Überwachungsaufträge

API-Request:
https://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:
https://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:
https://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.