API-Schnittstelle (Version 1.1)

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

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.

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		GERMANY 1		Überwachungsstandort, von welchem aus der Check durchgeführt wurde. Bei Ping- und 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

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 oder Handy-Nr des Empfängers.
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 oder TWITTER).
message		DOWN-Nachricht: ...		Inhalt der Benachrichtigung.

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>  </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.

API-Request: http://serverstate.de/api/1/sensors/?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'?> <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 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.

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.

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.

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.