API monitoring: jak sprawdzać odpowiedź JSON, nie tylko HTTP 200

W skrócie: API JSON może zwrócić HTTP 200 z ciałem {"status":"error","message":"DB unavailable"} - monitoring, który śledzi tylko kod statusu, ogłasza "UP". Prawdziwy monitoring API sprawdza również treść odpowiedzi, nie tylko warstwę HTTP.

Problem: HTTP 200 != działające API

Konwencje REST API mówią używać kodów statusu poprawnie (200 OK, 4xx client error, 5xx server error). W praktyce:

• Niektóre API zwracają zawsze 200, błąd jest w body JSON
• API gateway może transformować 5xx w 200 z error JSON
• Endpointy frontend BFF często wrappują backendy i zwracają 200, jeśli komunikacja się odbyła, nawet jeśli backend zawiódł
• Endpointy GraphQL zawsze zwracają 200, errors są w polu errors[]

Z perspektywy klasycznego monitoringu (kod statusu HTTP) wszystko jest OK. Z perspektywy prawdziwego klienta API się zepsuło.

Content matching: słowa kluczowe

Najprostszym dodatkiem do monitoringu HTTP jest keyword match. Definiujesz ciąg, który musi być w odpowiedzi - jeśli brakuje, alert.

Przykład dla endpointu health check:

GET /api/health HTTP/1.1

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

Keyword match ustawić na "status":"ok". Jeśli DB padnie i endpoint zwróci "status":"degraded", monitoring złapie.

Negative matching: co powinno brakować

Czasem przydatniejsze jest sprawdzanie, czy określonego ciągu NIE ma w odpowiedzi:

• "error" - błąd w body
• "maintenance" - nieoczekiwany tryb maintenance
• "deprecated" - endpoint API stał się deprecated
• fragmenty błędów SQL: "SyntaxError", "undefined", "null pointer" - przeciekające błędy backend

Zaawansowane asercje - roadmap

Plain text match ma ograniczenia. Dla poważnego API monitoringu odpowiednie są strukturalne asercje nad strukturą JSON (wyrażenia JSONPath) i wieloetapowe transakcje syntetyczne (login -> chroniony endpoint -> logout).

Asercje JSONPath i wieloetapowe transakcje syntetyczne są w roadmapie ePulz.io, ale obecnie nie są zaimplementowane. Jeśli potrzebujesz ich dziś, połącz ePulz.io HTTP monitor z własnym skryptem pomocniczym, który wysyła wynik przez monitor heartbeat (w przypadku awarii po prostu nie wysyłaj heartbeat).

Authentication w monitoringu

Monitorowany endpoint często wymaga auth. Opcje:

• Bearer token w nagłówku Authorization - typowo long-lived monitoring token bez wygaśnięcia (trzeba bezpiecznie przechować)
• Klucz API w query parametrze - widoczny w logach, nie preferowany
• Sygnatura HMAC - timestamp + URL + hash body podpisany shared secret. Najbezpieczniejsze.
• mTLS - cert klienta po stronie monitoringu. Odpowiednie dla wewnętrznych API.

Uwaga bezpieczeństwa: Dla monitoringu utwórz dedicated account / token z minimalnymi prawami (read-only health endpoint, nie admin token). Token rotuj regularnie. Jeśli serwis monitoringu wyciecze, nie ucieknie całego dostępu do API.

Response time SLO

Response time API jest równie ważny co kod HTTP. Klient z timeoutem 30 s nie widzi różnicy między "API zwraca 200 za 25 s" a "API timeoutowało". Z punktu UX oba są złe.

Ustaw:

• Hard timeout - po 10-15 s monitoring ogłasza DOWN
• Soft threshold - response time między 500-2000 ms = warning (degraded performance)
• Trending alerts - alert, jeśli 95. percentyl response time wzrośnie o 50% w ostatnich 24 h

Per-endpoint monitoring

Duże API ma dziesiątki endpointów. Nie monitoruj tylko /health - nawet on może kłamać. Zidentyfikuj 3-5 krytycznych endpointów:

• Najczęściej używane business operations (POST /api/orders, GET /api/dashboard)
• Read endpoint dla cache hit (szybka odpowiedź)
• Write endpoint z DB roundtrip
• External integration endpoint (woła trzecią stronę - wykrywa awarie zależności)

Każdy monitoruj osobno. Przy incydencie widzisz dokładnie, która część API padła.

Wnioski

Monitoringu API nie da się zredukować do kodu statusu HTTP. Jakościowy monitoring łączy status + content match + response time + per-endpoint granularność + authentication, by przypominać prawdziwego klienta - nie tylko klienta HTTP.

API monitoring z keyword match

Kod statusu + keyword w treści + response time + auth headers. Per-endpoint granularność.

Wypróbować na 7 dni →