Monitoring API

Dlaczego API potrzebuje własnego monitoringu

API to nie jest po prostu strona pod /api/. To kontrakt. Metoda HTTP ma znaczenie - GET vs POST zmienia semantykę. Nagłówki niosą uwierzytelnienie, content negotiation, klucze idempotentności. Body żądania to wejście. Kod odpowiedzi ma znaczenie (401 vs 403 vs 422 - każdy mówi inną historię). Body odpowiedzi ma strukturę - ścieżki JSON, na których polegają integratorzy. Zwykły check uptime, który tylko trafia URL przez GET, przegapi większość sposobów, na jakie API może paść: niepoprawny JSON wciąż zwracający 200, endpoint uwierzytelnienia akceptujący błędne dane, webhook z popsutym schematem payloadu, endpoint zwracający 200 ale z "status": "error" w środku.

Monitoring API rozwiązuje to, dając Ci kontrolę nad każdą częścią requestu i każdą częścią weryfikacji odpowiedzi. Konfigurujesz dokładnie taki call, jaki robią Twoi integratorzy - ta sama metoda, te same nagłówki, to samo body, to samo auth - i dokładnie to, co znaczy sukces - dokładne kody, wartości pod ścieżkami JSON, progi czasu odpowiedzi, granice rozmiaru.

Konfiguracja requestu

Dla każdego monitora API w DiagnoSEO Uptime Monitoring możesz skonfigurować:

• Metoda HTTP: GET, POST, PUT, PATCH, DELETE, HEAD. Wybierz tę, której używają integratorzy.
• Własne nagłówki: jako obiekt JSON, np. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Standard do testowania OAuth, JWT, kluczy API, content negotiation.
• Body żądania: dowolny string - JSON, XML, form-encoded, plain text. Wysyłany przy POST/PUT/PATCH/DELETE.
• Basic auth: użytkownik i hasło, jeśli endpoint jest tak chroniony.
• Oczekiwane kody statusu: lista lub zakres. Domyślnie 200-399, ale możesz zacisnąć do jednego kodu (np. dokładnie 201 dla endpointu tworzenia) lub dopuścić konkretne (np. 200,202,204).

Sprawdzenie podąża za maks. 5 redirectami, dekoduje gzip, parsuje Content-Type, by wykryć JSON. Każde sprawdzenie zapisuje rzeczywisty kod, czas odpowiedzi, rozmiar i ewentualny błąd. Wiele kolejnych awarii (konfigurowalne, domyślnie 2) wywołuje incydent.

Asercje JSON path

Same kody statusu nie wystarczą dla wielu API. Endpoint health może zwrócić 200 z body {"status": "degraded", "db": "down"} - wciąż 200, ale absolutnie chcesz to wiedzieć. API cen może zwrócić 200 z body, gdzie data.price spadło do null. API wyszukiwarki może zwrócić 200 z results: [], bo indeks padł.

Dla takich przypadków skonfiguruj asercję JSON path. Ustaw ścieżkę (np. data.status lub health.checks.db) i oczekiwaną wartość (np. healthy, true lub konkretną liczbę). Przy każdym sprawdzeniu odpowiedź jest dekodowana z JSON, a wartość pod ścieżką porównana. Niedopasowanie kończy check awarią, niezależnie od statusu HTTP.

Składnia ścieżki to notacja kropkowa z nawiasami: data.items[0].id działa, podobnie users.john.email. Asertowana wartość porównywana jest jako string, więc "true" pasuje do bool true, a liczby pasują i jako stringi i jako liczby.

Wzorce uwierzytelnienia

Dwa najczęstsze style auth działają out of the box. Dla tokenów Bearer (OAuth, JWT, API keys) użyj pola headers: {"Authorization": "Bearer eyJhbGciOi..."}. Token siedzi w konfiguracji monitora i jest wysyłany przy każdym sprawdzeniu. Dla basic auth użyj dedykowanych pól użytkownik/hasło - są przechowywane i łączone w standardowy nagłówek.

Jeśli auth wymaga podpisywania per-request lub odświeżania tokena, jest trudniej. Dwa rozsądne wzorce: (1) skonfiguruj długo żyjący token konta serwisowego specjalnie do monitoringu, lub (2) wystaw nieuwierzytelniony endpoint health, który odzwierciedla status prawdziwego chronionego, i monitoruj go. Większość nowoczesnych API ma to już out of the box.

Wzorce, które polecamy

• Jeden monitor na krytyczny endpoint. Nie testuj każdego - wybierz 5-10, których awaria oznaczałaby realną szkodę.
• Używaj dokładnych kodów. Domyślny 200-399 jest zbyt permisywny dla API. Endpoint tworzenia powinien zwrócić dokładnie 201; idempotentny dokładnie 200; endpoint logowania dokładnie 200 (sukces) lub 401 (well-formed failure - nie 500).
• Łącz status z asercją JSON. Razem łapią regresje warstwy transportowej i contentowej. Sam status nie złapie content errorów; sama JSON asercja jest krucha przy redirectach.
• Ustaw próg czasu odpowiedzi. Degradacja API to leading indicator problemów z zależnościami. Monitor z rt_threshold_ms = 800 mówi, że API zwalnia, zanim padnie.
• Trzymaj body małe. Sprawdzenie idzie co minutę - duże body marnują pasmo po obu stronach. Reprezentatywne-ale-minimalne payloady wystarczą.

Łącz z innymi typami monitorów

Dla każdego endpointu API monitor API weryfikuje, że call działa. Osobny monitor ping lub port weryfikuje, że host żyje. Sprawdzenie SSL/domeny na tej samej nazwie hosta łapie problemy z certyfikatem i rejestracją. Sub-monitor DNS pilnuje zmian rekordów, które mogłyby wskazywać na podmianę. Razem cztery monitory na API dają pełen obraz przy minimalnym nakładaniu się.

Konfiguracja

Otwórz narzędzie, kliknij "Dodaj monitor", wybierz typ "API". Wklej URL. Otwórz sekcję Zaawansowane. Wybierz metodę, wklej nagłówki jako JSON, wklej body jeśli potrzeba, ustaw basic auth jeśli używasz, wpisz oczekiwane kody (np. 200 lub 200,201). Dodaj asercję JSON path, jeśli aplikuje. Ustaw interwał i próg potwierdzenia. Zapisz. Od następnego cyklu monitor woła Twoje API dokładnie tak jak zrobiłby to integrator, waliduje odpowiedź i alarmuje w sekundzie regresji.

Najczęściej zadawane pytania

• Jakie metody HTTP mogę używać do monitoringu API?

  GET, POST, PUT, DELETE, PATCH i HEAD. Skonfiguruj metodę per monitor — dla endpointów write (POST/PUT/PATCH) body requestu też jest konfigurowalne jako string JSON lub form data.

• Jak działają asercje JSON?

  Podajesz ścieżkę JSON (np. data.status lub results[0].id) i oczekiwaną wartość. Monitor pobiera odpowiedź, parsuje jako JSON, ekstrahuje ścieżkę i porównuje z oczekiwaną. Jeśli się nie zgadza, check zawodzi z błędem "assertion failed" pokazującym rzeczywistą wartość.

• Czy mogę wysyłać nagłówki uwierzytelniania?

  Tak. Customowe nagłówki HTTP są konfigurowalne per monitor — tokeny Authorization, klucze API, content-type, cokolwiek. Wartości nagłówków są szyfrowane w spoczynku w bazie. Dla Basic Auth jest dedykowane pole username/password które automatycznie podpisuje request.

• Co jeśli moje API zwraca 200 z payloadem błędu?

  Powszechny pattern: API zwraca HTTP 200 ale body mówi {"status":"error"}. Naiwny monitor uptime myśli że to zdrowe. Użyj asercji JSON status == "ok" żeby to złapać — asercja zawodzi i monitor raportuje DOWN mimo że HTTP mówi 200.

• Jak obsłużyć API z rate limit?

  Ustaw interwał checków żeby respektował limit API (np. 5-minutowy interwał jeśli API pozwala na 12 wywołań/godzinę). Monitor liczy jako jedno wywołanie API per check z jednego regionu. Checki multi-region mnożą liczbę wywołań — używaj single-region jeśli Twoje API ma ścisłe limity.