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.

Twitter | Facebook