Monitorovanie API

Prečo API potrebuje vlastné monitorovanie

API nie je len stránka pod /api/. Je to kontrakt. HTTP metóda je dôležitá – GET vs POST mení sémantiku. Hlavičky nesú overovanie, content negotiation, idempotentné kľúče. Telo požiadavky je vstup. Kód odpovede je dôležitý (401 vs 403 vs 422 – každý rozpráva iný príbeh). Telo odpovede má štruktúru – JSON cesty, na ktoré sa spoliehajú integrátori. Obyčajná kontrola dostupnosti, ktorá len trafí URL cez GET, prehliadne väčšinu spôsobov, ako môže API zlyhať: neplatný JSON stále vracajúci 200, endpoint pre overenie prijímajúci nesprávne údaje, webhook s pokazenou schémou payloadu, endpoint vracajúci 200 ale s "status": "error" vo vnútri.

Monitorovanie API to rieši tým, že ti dáva kontrolu nad každou časťou požiadavky aj overenia odpovede. Nakonfiguruješ presne taký call, aký robia tvoji integrátori – rovnaká metóda, rovnaké hlavičky, rovnaké telo, rovnaké overenie – a presne to, čo znamená úspech – konkrétne kódy, hodnoty pod JSON cestami, prahy času odpovede, hranice veľkosti.

Konfigurácia požiadavky

Pre každý API monitor v DiagnoSEO Uptime Monitoring môžeš nastaviť:

• HTTP metóda: GET, POST, PUT, PATCH, DELETE, HEAD. Vyber tú, ktorú používajú integrátori.
• Vlastné hlavičky: ako JSON objekt, napr. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Štandard na testovanie OAuth, JWT, API kľúčov, content negotiation.
• Telo požiadavky: ľubovoľný reťazec – JSON, XML, form-encoded, obyčajný text. Posielané pri POST/PUT/PATCH/DELETE.
• Basic auth: používateľ a heslo, ak je endpoint takto chránený.
• Očakávané status kódy: zoznam alebo rozsah. V predvolenom nastavení 200-399, ale môžeš zúžiť na jeden kód (napr. presne 201 pre endpoint na vytváranie) alebo povoliť konkrétne (napr. 200,202,204).

Kontrola sleduje max. 5 presmerovaní, dekóduje gzip, parsuje Content-Type na zistenie JSONu. Každá kontrola zaznamená skutočný kód, čas odpovede, veľkosť a prípadnú chybu. Viacero po sebe idúcich zlyhaní (nastaviteľné, predvolená hodnota 2) spustí incident.

Asercie JSON path

Samotné status kódy nestačia pre mnohé API. Endpoint health môže vrátiť 200 s telom {"status": "degraded", "db": "down"} – stále 200, ale určite o tom chceš vedieť. Cenové API môže vrátiť 200 s telom, kde data.price kleslo na null. Vyhľadávacie API môže vrátiť 200 s results: [], lebo index spadol.

Pre tieto prípady nastav aserciu JSON path. Zadaj cestu (napr. data.status alebo health.checks.db) a očakávanú hodnotu (napr. healthy, true alebo konkrétne číslo). Pri každej kontrole sa odpoveď dekóduje z JSON a hodnota pod cestou sa porovná. Nezhoda ukončí check ako zlyhanie, bez ohľadu na HTTP status.

Syntaktika cesty sú bodková notácia s hranatými zátvorkami: data.items[0].id funguje, rovnako users.john.email. Asertovaná hodnota sa porovnáva ako reťazec, takže "true" sedí na bool true, a čísla sedia ako reťazce aj ako čísla.

Vzory autentifikácie

Dva najčastejšie štýly overenia fungujú hneď. Pre Bearer tokeny (OAuth, JWT, API kľúče) použite pole headers: {"Authorization": "Bearer eyJhbGciOi..."}. Token je v konfigurácii monitora a posiela sa pri každej kontrole. Pre basic auth použite vyhradené polia používateľ/heslo – uchovávajú sa a automaticky sa zlúčia do štandardnej hlavičky.

Ak overenie vyžaduje podpisovanie každej požiadavky alebo obnovovanie tokenu, je to zložitejšie. Dva rozumné vzory: (1) nakonfiguruj dlhodobý token servisného účtu špeciálne pre monitoring, alebo (2) sprístupni neoverený endpoint health, ktorý odráža stav skutočného chráneného endpointu, a monitoruj ho. Väčšina moderných API to má už hneď k dispozícii.

Vzory, ktoré odporúčame

• Jeden monitor na kritický endpoint. Netestuj každý – vyber 5–10, ktorých výpadok by znamenal reálnu škodu.
• Používaj presné kódy. Predvolený 200–399 je pre API príliš povolný. Endpoint vytvárania má vracať presne 201, idempotentný presne 200, endpoint prihlasovania presne 200 (úspech) alebo 401 (správne odmietnutie – nie 500).
• Kombinuj status s JSON aserciou. Spolu zachytia regresie v transportnej aj obsahovej vrstve. Samotný status nezachytí chyby obsahu, samotná JSON asercia je nestabilná pri presmerovaní.
• Nastav prah odpovedného času. Degradácia API je včasným indikátorom problémov so závislosťami. Monitor s rt_threshold_ms = 800 hovorí, že API spomaľuje, ešte pred výpadkom.
• Drž telo malé. Kontrola prebieha každú minútu – veľké telo plytvá šírkou pásma na oboch stranách. Reprezentatívne, ale minimálne payloady stačia.

Kombinuj s inými typmi monitorov

Pre každý API endpoint monitor API overuje, že volanie funguje. Samostatný ping alebo port monitor overuje, že host beží. Kontrola SSL/domény na tom istom hoste odhalí problémy s certifikátom a registráciou. DNS sub-monitor sleduje zmeny záznamov, ktoré by mohli naznačovať podvrhnutie. Spolu štyri monitory na API dávajú celkový pohľad s minimálnym prekrývaním.

Konfigurácia

Otvorte nástroj, kliknite na „Pridať monitor“, zvoľte typ „API“. Vložte URL. Otvorte sekciu Pokročilé. Vyberte metódu, vložte hlavičky ako JSON, vložte telo podľa potreby, nastavte basic auth, ak používate, zadajte očakávané kódy (napr. 200 alebo 200,201). Pridajte aserciu JSON path, ak je potrebná. Nastavte interval a prah potvrdenia. Uložte. Od ďalšieho cyklu bude monitor volať vaše API presne tak, ako to robí integrátor, validuje odpoveď a v momente regresie upozorní.

Najčastejšie otázky

• Aké HTTP metódy môžem použiť na monitorovanie API?

  GET, POST, PUT, DELETE, PATCH a HEAD. Nakonfigurujete metódu pre každý monitor — pre zápisové endpointy (POST/PUT/PATCH) je telo požiadavky tiež nastaviteľné ako JSON string alebo form data.

• Ako fungujú JSON asercie?

  Zadáš JSON cestu (napr. data.status alebo results[0].id) a očakávanú hodnotu. Monitor stiahne odpoveď, rozparsuje ju ako JSON, extrahuje cestu a porovná s očakávanou hodnotou. Ak sa nezhoduje, check zlyhá s chybou „assertion failed“ a zobrazí skutočnú hodnotu.

• Môžem posielať autentifikačné hlavičky?

  Áno. Vlastné HTTP hlavičky sú konfigurovateľné pre každý monitor — Authorization tokeny, API kľúče, content-type, čokoľvek. Hodnoty hlavičiek sú v databáze šifrované v pokoji. Pre Basic Auth je vyhradené pole pre username/password, ktoré automaticky podpisuje požiadavku.

• Čo ak moje API vracia 200 s chybovým payloadom?

  Bežný scenár: API vráti HTTP 200, ale telo hlási {"status":"error"}. Naivný uptime monitor si myslí, že je to v poriadku. Použi JSON aserciu status == "ok" na odhalenie — asercia zlyhá a monitor ohlási DOWN, hoci HTTP vraví 200.

• Ako zvládnuť API s rate limit?

  Nastav si interval kontrol tak, aby rešpektoval limit API (napr. 5-minútový interval, ak API povoľuje 12 volaní/hodinu). Monitor počíta ako jedno API volanie na jeden check z jedného regiónu. Multi-region checky zvyšujú počet volaní — použi single-region ak má vaše API prísne limity.