Dokumentation

API-Monitoring: JSON, XML, HTML und Header prüfen

Ein Server, der mit 200 OK antwortet und dabei eine Fehlerseite, eine leere Liste oder die Daten von gestern ausliefert, ist, gemessen am Statuscode, erreichbar – und für alle, die ihn nutzen, trotzdem kaputt. Pingsured kann deshalb nicht nur prüfen, ob eine Antwort ankommt, sondern auch, was in ihr steht.

Alle folgenden Prüfungen sind optional und lassen sich beliebig kombinieren. Ein Ping gilt nur dann als erfolgreich, wenn der Statuscode passt und jede eingerichtete Inhaltsprüfung besteht.

Statuscode

Der erwartete Status ist ein einzelner Code, eine Liste oder ein Bereich: 200, 200,204 oder 200-299. Alles andere gilt als Fehler. Voreingestellt ist 200.

Text im Inhalt

Die einfachste Inhaltsprüfung: Die Antwort muss einen bestimmten Text enthalten, etwa einen Produktnamen oder die Kennung, die Ihr Health-Endpunkt bei Erfolg ausgibt. Gesucht wird ein einfacher Teiltext von bis zu 1.024 Zeichen.

JSON-Felder (JSONPath)

Für APIs wählen Sie mit einem JSONPath-Ausdruck einen Wert aus und vergleichen ihn. Ein Health-Endpunkt, der {"status": "ok", "queue": {"depth": 12}} liefert, lässt sich zum Beispiel so überwachen:

Verfügbare Operatoren:

• vorhanden / nicht vorhanden – der Pfad trifft etwas oder nichts.
• gleich / ungleich – typgenau: Die Zahl 12 ist nicht gleich der Zeichenkette "12".
• enthält und passt auf (regulärer Ausdruck) für Text.
• größer / kleiner als (oder gleich) für Zahlen.
• Anzahl-Vergleiche für die Zahl der Treffer, etwa „mindestens ein Eintrag in $.items[*]“.
• Alter-Vergleiche für Zeitstempel, siehe „Aktualität“ weiter unten.

Trifft ein Pfad mehrere Werte, wird der erste verglichen. Bis zu 16 JSON-Prüfungen pro Ping.

XML-Elemente (XPath)

Dasselbe für XML-Antworten – Feeds, SOAP-Dienste, Sitemaps – mit XPath-Ausdrücken wie /rss/channel/item (Anzahl mindestens 1) oder //status/text() (gleich ok). Operatoren: vorhanden, nicht vorhanden, gleich, enthält, passt auf, die Anzahl- und Alter-Vergleiche. Eine Antwort, die kein wohlgeformtes XML ist, lässt jede XML-Prüfung scheitern.

HTML-Elemente (CSS-Selektoren)

Für Webseiten wählen Sie ein Element per CSS-Selektor – oder per XPath, wenn Ihnen das lieber ist – und prüfen seinen Text oder eines seiner Attribute. Leerraum im Text wird vor dem Vergleich vereinheitlicht, Zeilenumbrüche im Markup spielen also keine Rolle. Typische Fälle:

• das Preis-Element auf einer Produktseite ist vorhanden und nicht leer;
• h1.title enthält Ihre Überschrift, sodass ein leeres Template oder eine Wartungsseite auffällt;
• das content-Attribut eines meta-Tags hat den richtigen Wert.

Antwort-Header

Header lassen sich auf zwei Arten prüfen: als exakter Vergleich pro Header oder mit denselben Operatoren wie oben – vorhanden, nicht vorhanden, gleich, enthält, passt auf, Zahlenvergleiche und Alter. Header-Prüfungen lesen den Inhalt der Antwort nicht.

Aktualität: Wie alt sind die Daten?

Die Alter-Operatoren lesen einen Wert als Zeitstempel und vergleichen sein Alter in Sekunden. „$.updated_at Alter kleiner als 3600“ schlägt fehl, sobald die neuesten Daten älter als eine Stunde sind – der klassische Fall eines Exports, Caches oder Feeds, der unbemerkt stehen geblieben ist, während der Server weiter antwortet.

Erkannte Formate:

• ISO 8601 / RFC 3339, etwa 2026-10-09T14:30:00Z (eine Zeit ohne Zeitzone gilt als UTC);
• HTTP-Datumsangaben, ein Last-Modified-Header funktioniert also ohne Weiteres;
• Unix-Zeit in Sekunden oder Millisekunden.

Gut zu wissen

• Der Inhalt wird bis 1 MB gelesen.
• Geprüft wird mit GET- oder HEAD-Anfragen. Andere Methoden und Anfrage-Inhalte gibt es noch nicht: Weil sie Daten auf dem geprüften Server verändern können, setzen sie künftig einen Nachweis voraus, dass Ihnen die Domain gehört.
• Für Endpunkte mit Token oder Login können Sie bis zu 20 eigene Anfrage-Header und HTTP-Basic-Authentifizierung angeben.
• Der User-Agent ist immer Pingsured/1.0, mit einem Link auf die Seite, die Server-Betreibern unsere Anfragen erklärt.