API-Monitoring: wenn HTTP 200 nicht ausreicht

Eine JSON-API kann HTTP 200 mit einem Fehler im Body zurueckgeben - ein Monitoring nach Statuscode meldet UP. Echtes API-Monitoring prueft auch den Inhalt der Antwort, nicht nur HTTP.

Das Problem: HTTP 200 != funktionierende API

Laut REST-API-Konventionen sollten Statuscodes korrekt verwendet werden (200 OK, 4xx Client Error, 5xx Server Error). In der Praxis:

Manche APIs geben immer 200 zurueck, der Fehler steckt im JSON-Body
Ein API-Gateway kann einen 5xx in einen 200 mit Error-JSON umwandeln
Frontend-BFF-Endpunkte umhuellen oft Backends und geben 200 zurueck, wenn die Kommunikation geklappt hat, auch wenn das Backend fehlgeschlagen ist
GraphQL-Endpunkte geben typischerweise 200 zurueck; Fehler (errors) stehen im Array errors[]

Aus Sicht des klassischen Monitorings (HTTP-Statuscode) ist alles in Ordnung. Aus Sicht eines echten Clients ist die API kaputt.

Content-Matching: Schluesselwoerter

Die einfachste Ergaenzung zum HTTP-Monitoring ist ein Schluesselwort-Abgleich. Sie definieren eine Zeichenkette, die in der Antwort vorhanden sein muss - fehlt sie, kommt eine Benachrichtigung.

Beispiel fuer einen Health-Check-Endpunkt:

GET /api/health HTTP/1.1

{
  "status": "ok",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  },
  "version": "1.42.3"
}

Stellen Sie den Keyword-Match auf "status":"ok". Faellt die DB aus und der Endpunkt liefert "status":"degraded", faengt das Monitoring es ab.

Negative-Matching: was fehlen sollte

Manchmal ist es nuetzlicher zu pruefen, dass eine bestimmte Zeichenkette NICHT in der Antwort vorkommt:

"error" - ein Fehler im Body
"maintenance" - ein unerwarteter Wartungsmodus
"deprecated" - der API-Endpunkt wurde als veraltet (deprecated) markiert
SQL-Fehlerfragmente: "SyntaxError", "undefined", "null pointer" - durchsickernde Backend-Fehler

Fortgeschrittene Assertions

Plain-Text-Matching hat seine Grenzen. Fuer ernsthaftes API-Monitoring eignen sich strukturierte Assertions ueber die JSON-Struktur (JSONPath-Ausdruecke) und mehrstufige synthetische Transaktionen (Login -> geschuetzter Endpunkt -> Logout).

ePulz.io unterstuetzt diese Optionen direkt. Das Multi-Step- / API-Monitoring erlaubt es, bis zu 10 Schritte zu verketten (GET/POST/PUT/PATCH/DELETE/HEAD), bei jedem Schritt den Statuscode, den Inhalt und einen JSONPath-Wert zu pruefen und Variablen aus der Antwort fuer weitere Schritte zu speichern. Die Funktion ist in den Tarifen Profi und Business verfuegbar und laeuft auf der primaeren Region. Fuer einfachere Faelle in niedrigeren Tarifen koennen Sie einen HTTP-Monitor mit einem separaten Hilfsskript kombinieren, das das Ergebnis ueber einen Heartbeat-Monitor sendet.

Authentifizierung im Monitoring

Ein ueberwachter Endpunkt erfordert oft Auth. Moeglichkeiten:

Bearer Token im Authorization-Header - typischerweise ein langlebiger Monitoring-Token ohne Ablauf (sicher speichern)
API-Key im Query-Parameter - in den Logs sichtbar, nicht bevorzugt
HMAC-Signatur - Timestamp + URL + Body-Hash, signiert mit einem Shared Secret. Am sichersten.
mTLS - ein Client-Zertifikat auf der Monitoring-Seite. Geeignet fuer interne APIs.

Sicherheitshinweis: Erstellen Sie fuer das Monitoring ein dediziertes Konto / Token mit minimalen Rechten (read-only Health-Endpunkt, kein Admin-Token). Rotieren Sie den Token regelmaessig. Wird der Monitoring-Dienst kompromittiert, leckt nicht der gesamte Zugriff auf die API.

SLO der Antwortzeit

Die Antwortzeit der API ist genauso wichtig wie der HTTP-Code. Ein Client mit 30 s Timeout sieht keinen Unterschied zwischen "die API liefert 200 in 25 s" und "die API ist in einen Timeout gelaufen". Aus UX-Sicht sind beide schlecht.

Stellen Sie ein:

Hard Timeout - nach 10-15 s meldet das Monitoring DOWN
Soft Threshold - eine Antwortzeit zwischen 500-2000 ms = Warning (degraded performance)
Trend-Benachrichtigungen - eine Benachrichtigung, wenn das 95. Perzentil der Antwortzeit in den letzten 24 h um 50 % steigt

Per-Endpoint-Monitoring

Eine grosse API hat Dutzende Endpunkte. Ueberwachen Sie nicht nur /health - auch der kann luegen. Identifizieren Sie 3-5 kritische Endpunkte:

Die meistgenutzten Business-Operationen (POST /api/orders, GET /api/dashboard)
Einen Lese-Endpunkt, der einen Cache-Hit testet (schnelle Antwort)
Einen Schreib-Endpunkt mit DB-Roundtrip
Einen External-Integration-Endpunkt (ruft einen Dritten auf - erkennt Ausfaelle von Abhaengigkeiten)

Ueberwachen Sie jeden einzeln. Bei einem Incident sehen Sie so genau, welcher Teil der API ausgefallen ist.

Fazit

API-Monitoring laesst sich nicht auf einen HTTP-Statuscode reduzieren. Gutes Monitoring kombiniert Status + Content-Match + Antwortzeit + Per-Endpoint-Granularitaet + Authentifizierung, um einen echten Client treu nachzubilden - nicht nur einen HTTP-Client.

API-Monitoring mit Schluesselwort-Abgleich

Statuscode + Keyword im Inhalt + Antwortzeit + Auth-Header. Per-Endpoint-Granularitaet.

Monitoring starten →