Monitorování API

Proč API potřebuje vlastní monitoring

API není jen stránka pod /api/. Je to kontrakt. Metoda HTTP je důležitá – GET vs POST mění sémantiku. Hlavičky nesou autentizaci, content negotiation, idempotentní klíče. Tělo požadavku je vstup. Kód odpovědi je důležitý (401 vs 403 vs 422 – každý říká něco jiného). Tělo odpovědi má strukturu – JSON cesty, na které se integrátoři spoléhají. Běžný kontrolní uptime check, který pouze načte URL přes GET, přehlédne většinu způsobů, jakými může API spadnout: nevalidní JSON vracející stále 200, endpoint autentizace akceptující chybné údaje, webhook s rozbitým payloadem, endpoint vracející 200 ale s "status": "error" uvnitř.

Monitoring API to řeší tím, že Ti dává kontrolu nad každou částí requestu i verifikace odpovědi. Nastavíš přesně takový call, jaký dělají Tvoji integrátoři – stejná metoda, stejné hlavičky, stejné tělo, stejná autentizace – a přesně co znamená úspěch – konkrétní kódy, hodnoty pod JSON cestami, limity času odpovědi, hranice velikosti.

Nastavení requestu

Pro každý monitor API v DiagnoSEO Uptime Monitoring můžeš nastavit:

• Metoda HTTP: GET, POST, PUT, PATCH, DELETE, HEAD. Vyber tu, kterou používají integrátoři.
• Vlastní hlavičky: jako JSON objekt, např. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Standardní pro testování OAuth, JWT, API klíčů, content negotiation.
• Tělo požadavku: libovolný string – JSON, XML, form-encoded, prostý text. Odesílá se u POST/PUT/PATCH/DELETE.
• Basic auth: uživatel a heslo, pokud je endpoint takto chráněn.
• Očekávané kódy statusu: seznam nebo rozsah. Standardně 200-399, ale můžeš nastavit přesně jeden kód (např. přesně 201 pro endpoint na vytvoření) nebo povolit konkrétní (např. 200,202,204).

Kontrola následuje max. 5 přesměrování, dekóduje gzip, parsuje Content-Type pro detekci JSON. Každá kontrola zaznamenává skutečný kód, odpovědní čas, velikost a případnou chybu. Více po sobě jdoucích selhání (nastavitelně, ve výchozím stavu 2) vyvolá incident.

JSON path aserce

Samo o sobě status kódy mnoha API nestačí. Health endpoint může vrátit 200 s tělem {"status": "degraded", "db": "down"} – pořád 200, ale rozhodně o tom chceš vědět. API cen může vrátit 200 s tělem, kde data.price je najednou null. Vyhledávací API může vrátit 200 s results: [], protože index spadl.

Pro takové případy nastav aserci JSON path. Uveď cestu (např. data.status nebo health.checks.db) a očekávanou hodnotu (např. healthy, true nebo číslo). Při každé kontrole je odpověď dekódována z JSON a hodnota pod cestou porovnána. Neshoda znamená selhání kontroly bez ohledu na HTTP status.

Skladba cesty je tečková notace s hranatými závorkami: data.items[0].id funguje, stejně tak users.john.email. Asertovaná hodnota je porovnávána jako string, takže "true" odpovídá bool true, a čísla odpovídají jak jako string, tak číslo.

Muster autentizace

Dva nejčastější styly autentizace fungují přímo z krabice. Pro Bearer tokeny (OAuth, JWT, API klíče) použij pole headers: {"Authorization": "Bearer eyJhbGciOi..."}. Token je uložen v konfiguraci monitoru a posílán při každé kontrole. Pro basic auth použij dedikovaná pole uživatel/heslo – ukládají se a jsou spojovány do standardní hlavičky.

Pokud autentizace vyžaduje podepisování každého požadavku zvlášť nebo obnovování tokenu, je to složitější. Dva rozumné vzory: (1) nakonfiguruj dlouhožijící token pro servisní účet zvlášť pro monitoring, nebo (2) vystav neautentizovaný health endpoint, který odráží stav skutečného chráněného a monitoruj ten. Většina moderních API už to tak má built-in.

Muster, které doporučujeme

• Jeden monitor na kritický endpoint. Není třeba testovat všechny – vyber 5–10, jejichž výpadek znamená reálný problém.
• Používej přesné kódy. Výchozí 200–399 je pro API příliš permisivní. Endpoint na vytvoření by měl vracet přesně 201; idempotentní přesně 200; endpoint pro přihlášení přesně 200 (úspěch) nebo 401 (korektní odmítnutí – ne 500).
• Kombinuj status s JSON asercí. Spolu zachytí jak regresi transportní vrstvy, tak obsahovou. Samotný status nechytí chyby obsahu; samotná JSON aserce je křehká při přesměrování.
• Nastav limit doby odezvy. Degradace API bývá časný indikátor potíží se závislostmi. Monitor s rt_threshold_ms = 800 hlásí, že API se zpomaluje, dříve než spadne.
• Drž tělo malé. Kontrola běží každou minutu – velké tělo zbytečně plýtvá šířkou pásma na obou stranách. Reprezentativní, ale minimální payloady stačí.

Kombinace s dalšími typy monitorů

Pro každý endpoint API ověřuje API monitor, že volání funguje. Samostatný ping nebo port monitor hlídá, že host žije. Kontrola SSL/domény na stejném hostname zachytí problémy s certifikátem nebo registrací. Sub-monitor DNS kontroluje změny záznamů, které by mohly signalizovat podvrh. Dohromady čtyři monitory na API dávají kompletní obraz s minimálním překryvem.

Nastavení

Otevři nástroj, klikni „Přidat monitor“, vyber typ „API“. Vlož URL. Otevři sekci Pokročilé. Vyber metodu, vlož hlavičky jako JSON, vlož tělo pokud je třeba, nastav basic auth pokud používáš, zadej očekávané kódy (např. 200 nebo 200,201). Přidej aserci JSON path pokud platí. Nastav interval a potvrzovací práh. Ulož. Od příštího cyklu monitor volá Tvé API přesně jako by to udělal integrátor, validuje odpověď a alarmuje při detekci regrese během sekundy.

Nejčastější dotazy

• Jaké HTTP metody mohu použít pro monitoring API?

  GET, POST, PUT, DELETE, PATCH a HEAD. Nastav metodu pro každý monitor – pro endpointy typu zápisu (POST/PUT/PATCH) je možné tělo requestu nakonfigurovat také jako JSON string nebo form data.

• Jak fungují JSON aserce?

  Zadáš JSON cestu (např. data.status nebo results[0].id) a očekávanou hodnotu. Monitor načte odpověď, parsuje jako JSON, vytáhne hodnotu podle cesty a porovná ji s očekávanou. Pokud neodpovídá, kontrola selže s chybou „assertion failed“ zobrazující skutečnou hodnotu.

• Mohu posílat autentizační hlavičky?

  Ano. Vlastní HTTP hlavičky lze nastavit pro každý monitor – Authorization tokeny, API klíče, content-type, cokoliv. Hodnoty hlaviček jsou v databázi šifrovány v klidovém stavu. Pro Basic Auth je k dispozici zvláštní pole username/password, které automaticky podepíše požadavek.

• Co když moje API vrátí 200 s error payloadem?

  Běžný vzor: API vrátí HTTP 200, ale tělo říká {"status":"error"}. Naivní uptime monitor si myslí, že je vše v pořádku. Použij JSON aserci status == "ok" k zachycení – aserce selže a monitor nahlásí DOWN i přesto, že HTTP vrací 200.

• Jak řešit API s rate limitem?

  Nastav interval kontrol tak, aby respektoval limit API (např. 5minutový interval pokud API umožňuje 12 volání/hod). Jeden monitor znamená jedno volání API z daného regionu. Multi-region kontroly násobí počet volání – používej single-region, pokud Tvé API má přísné limity.