Dokumentation

Prüfen, ob Ihre API richtig antwortet – nicht nur, ob sie antwortet

Die meisten API-Ausfälle sehen für eine Statuscode-Prüfung gar nicht nach Ausfall aus. Das Framework fängt die Exception ab und antwortet mit 200 OK und {"error": "database unavailable"}. Ein fehlgeschlagener Import hinterlässt eine leere Produktliste. Ein Cache liefert weiter alte Daten, weil der Job, der ihn befüllt, nicht mehr läuft. All das ist „erreichbar“ – und für jeden Client, der die API aufruft, trotzdem kaputt.

Pingsured liest das JSON in der Antwort und prüft genau die Werte, an denen Sie erkennen, ob die API tatsächlich funktioniert.

Was Sie prüfen sollten

Am einfachsten fangen Sie mit einem Health-Endpunkt an, der den Zustand seiner Abhängigkeiten meldet. Liefert er {"status": "ok", "db": "ok", "queue": {"depth": 12}}:

Die letzte Zeile sagt Ihnen, was ein Statuscode nie verrät: Die API ist erreichbar, und die Arbeit dahinter staut sich nicht.

Bei einem Endpunkt, der Daten statt eines Status liefert, prüfen Sie die Daten selbst:

Eine leere Liste, ein Preis von null und eine Antwort, die älter als fünfzehn Minuten ist, lassen den Ping jeweils scheitern – auch wenn der Server weiter mit 200 antwortet.

Endpunkte mit Zugangsdaten

Geben Sie die Header an, die die API erwartet – ein Authorization: Bearer-Token, einen API-Key-Header – oder nutzen Sie HTTP-Basic-Authentifizierung. Legen Sie für die Prüfung ein eigenes Token an, das nur lesen darf: Es wird mit dem Ping gespeichert, und ein Token nur für das Monitoring lässt sich widerrufen, ohne dass sonst etwas ausfällt.

Warum Sie Ihre API mit Pingsured prüfen sollten

• Typgenaue Vergleiche. Die Zahl 12 ist nicht gleich der Zeichenkette "12". Eine Änderung der Serialisierung, die aus Zahlen Zeichenketten macht – und damit bei jedem streng typisierten Client zu Fehlern führt –, lässt die Prüfung scheitern, statt durchzurutschen.
• Aktualität ohne eigenes Skript. Die Alter-Operatoren lesen ISO-8601-Zeitstempel, HTTP-Datumsangaben und Unix-Zeit. „Die Daten sind jünger als eine Stunde“ ist damit eine Zeile – und kein Cronjob, den Sie auch noch überwachen müssten.
• Bis zu 16 JSON-Prüfungen pro Ping, frei kombinierbar mit dem Statuscode, einer Header-Prüfung und einer Textsuche. Der Ping besteht nur, wenn alle bestehen.
• Geprüft von dort, wo Ihre Clients sind. Jeder Standort wird für sich bewertet. Eine API, die hinter einem CDN-Knoten oder aus einer Region heraus ausfällt, wird nicht von den anderen Standorten verdeckt.
• Alarme dort, wo Sie arbeiten. Standardmäßig per E-Mail und in der App; ab dem Team-Tarif auch per Webhook an Ihr Incident-Tool oder Ihren Chat.
• Die Details Ihrer API bleiben in der EU. Endpunkte, Header und Tokens gehören zu dem, was ein Monitoring-Konto speichert. Pingsured speichert sie in Deutschland und Finnland, ohne US-Dienst im Datenweg.

Grenzen, die Sie kennen sollten

• Geprüft wird mit GET oder HEAD. Eine API, die nur per POST erreichbar ist – die meisten GraphQL-Setups, SOAP –, lässt sich noch nicht prüfen.
• Jede Prüfung ist eine einzelne Anfrage. Ein Ablauf, der sich erst anmeldet und dann mit der erhaltenen Sitzung die API aufruft, ist nicht möglich; ein langlebiges Token im Header schon.
• Gelesen wird nur das erste MB der Antwort, und dort abgeschnittenes JSON lässt sich nicht mehr parsen. Richten Sie die Prüfung auf einen kleinen Endpunkt oder eine Seite einer Liste, nicht auf einen vollständigen Export.