Monitoring API: gdy HTTP 200 nie wystarcza

API JSON może zwrócić HTTP 200 z treścią o błędzie - monitoring oparty o kod statusu uzna stan za UP. Prawdziwy monitoring API sprawdza także zawartość odpowiedzi, nie tylko HTTP.

Problem: HTTP 200 ≠ działające API

Zgodnie z konwencjami REST API kody statusu powinny być używane poprawnie (200 OK, 4xx błąd klienta, 5xx błąd serwera). W praktyce:

Niektóre API zawsze zwracają 200, a błąd jest w treści JSON
Brama API (API gateway) może przekształcić 5xx na 200 z błędem w JSON
Frontendowe endpointy BFF często opakowują backendy i zwracają 200, jeśli komunikacja się powiodła, nawet gdy backend zawiódł
Endpointy GraphQL zazwyczaj zwracają 200; błędy (errors) znajdują się w polu errors[]

Z perspektywy klasycznego monitoringu (kod statusu HTTP) wszystko jest w porządku. Z perspektywy realnego klienta API się zepsuło.

Dopasowanie treści: słowa kluczowe

Najprostszym uzupełnieniem monitoringu HTTP jest dopasowanie słowa kluczowego. Definiujesz ciąg znaków, który musi znaleźć się w odpowiedzi - jeśli go brakuje, przychodzi powiadomienie.

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"
}

Dopasowanie słowa kluczowego ustaw na "status":"ok". Jeśli baza danych padnie, a endpoint zwróci "status":"degraded", monitoring to wychwyci.

Dopasowanie negatywne: czego powinno brakować

Czasem bardziej przydatne jest sprawdzanie, że określony ciąg NIE występuje w odpowiedzi:

"error" - błąd w treści
"maintenance" - nieoczekiwany tryb konserwacji
"deprecated" - endpoint API został oznaczony jako przestarzały (deprecated)
Fragmenty błędów SQL: "SyntaxError", "undefined", "null pointer" - przeciekające błędy backendu

Zaawansowane asercje

Dopasowanie zwykłego tekstu ma swoje ograniczenia. Do poważnego monitoringu API odpowiednie są ustrukturyzowane asercje na strukturze JSON (wyrażenia JSONPath) oraz wielokrokowe transakcje syntetyczne (logowanie -> chroniony endpoint -> wylogowanie).

ePulz.io obsługuje te możliwości bezpośrednio. Monitoring wielokrokowy / API pozwala łączyć w łańcuch do 10 kroków (GET/POST/PUT/PATCH/DELETE/HEAD), przy każdym kroku weryfikować kod statusu, zawartość oraz wartość JSONPath, a także zapisywać zmienne z odpowiedzi na potrzeby kolejnych kroków. Funkcja jest dostępna w planach Pro i Business oraz działa w regionie podstawowym. W prostszych przypadkach na niższych planach możesz połączyć monitor HTTP z osobnym skryptem pomocniczym, który wysyła wynik przez monitor heartbeat.

Uwierzytelnianie w monitoringu

Monitorowany endpoint często wymaga uwierzytelnienia. Możliwości:

Token Bearer w nagłówku Authorization - zazwyczaj długoterminowy token monitoringu bez wygaśnięcia (trzeba go bezpiecznie przechowywać)
Klucz API w parametrze zapytania - widoczny w logach, niezalecany
Podpis HMAC - timestamp + URL + hash treści podpisane współdzielonym sekretem. Najbezpieczniejszy.
mTLS - certyfikat klienta po stronie monitoringu. Odpowiedni dla wewnętrznych API.

Uwaga dotycząca bezpieczeństwa: Na potrzeby monitoringu utwórz dedykowane konto / token z minimalnymi uprawnieniami (endpoint health tylko do odczytu, a nie token administratora). Token rotuj regularnie. Jeśli usługa monitoringu zostanie naruszona, nie wycieknie pełny dostęp do API.

SLO czasu odpowiedzi

Czas odpowiedzi API jest równie ważny jak kod HTTP. Klient z limitem czasu 30 s nie widzi różnicy między "API zwróci 200 po 25 s" a "API zakończyło się timeoutem". Z punktu widzenia UX oba są złe.

Ustaw:

Twardy limit czasu - po 10-15 s monitoring zgłasza DOWN
Próg miękki - czas odpowiedzi między 500-2000 ms = ostrzeżenie (degraded performance)
Powiadomienia trendowe - powiadomienie, jeśli 95. percentyl czasu odpowiedzi wzrośnie o 50 % w ciągu ostatnich 24 h

Monitoring per endpoint

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

Najczęściej używane operacje biznesowe (POST /api/orders, GET /api/dashboard)
Endpoint do odczytu testujący trafienie w cache (szybka odpowiedź)
Endpoint do zapisu z rundą do bazy danych
Endpoint integracji zewnętrznej (wywołuje stronę trzecią - wykrywa awarie zależności)

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

Podsumowanie

Monitoringu API nie da się sprowadzić do kodu statusu HTTP. Dobry monitoring łączy status + dopasowanie treści + czas odpowiedzi + granularność per endpoint + uwierzytelnianie, aby wiernie naśladować realnego klienta - nie tylko klienta HTTP.

Monitoring API z dopasowaniem słowa kluczowego

Kod statusu + słowo kluczowe w treści + czas odpowiedzi + nagłówki auth. Granularność per endpoint.

Uruchom monitoring →