Spremljanje API-jev

Zakaj API potrebuje lasten monitoring

API ni zgolj stran pod /api/. To je pogodba. HTTP metoda je pomembna – GET proti POST spremeni pomen. Glave nosijo avtentikacijo, usmerjanje vsebine, idempotentne ključe. Body zahteve je vhod. Povratna koda je pomembna (401 proti 403 proti 422 – vsaka pove svojo zgodbo). Body odziva ima strukturo – JSON poti, na katere se zanašajo integratorji. Navaden uptime check, ki le zadene URL z GET, spregleda večino načinov, kako API lahko odpove: napačen JSON še vedno vrne 200, avtentikacijska točka sprejme napačne podatke, webhook s polomljeno shemo podatkov, endpoint vrne 200, a z "status": "error" v sredini.

API monitoring to reši, saj ti da popoln nadzor nad vsako komponento zahteve in overjanja odziva. Nastaviš točno tak klic, kot ga izvajajo tvoji integratorji – ista metoda, iste glave, isti body, ista avtentikacija – in točno kaj šteje za uspeh – točne kode, vrednosti po JSON poteh, meje časa odziva, meje velikosti.

Konfiguracija zahteve

Za vsak API monitor v DiagnoSEO Uptime Monitoring lahko nastaviš:

• HTTP metoda: GET, POST, PUT, PATCH, DELETE, HEAD. Izberi tisto, ki jo uporabljajo tvoji integratorji.
• Lastne glave: kot JSON objekt, npr. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Standardno za testiranje OAuth, JWT, API ključev, dogovor vsebine.
• Body zahteve: kateri koli niz – JSON, XML, form-encoded, navaden tekst. Pošlje se pri POST/PUT/PATCH/DELETE.
• Basic auth: uporabniško ime in geslo, če je endpoint tako zaščiten.
• Pričakovane kode statusa: seznam ali razpon. Privzeto 200-399, a lahko zožiš na točno eno kodo (npr. točno 201 za endpoint kreiranja) ali dovoliš določene (npr. 200,202,204).

Preverjanje sledi največ 5 preusmeritvam, dekodira gzip, razbere Content-Type, da zazna JSON. Vsak pregled shrani dejansko kodo, čas odziva, velikost in morebitno napako. Več zaporednih neuspehov (nastavljivo, privzeto 2) požene incident.

JSON path asercije

Sami status kodi niso dovolj za večino API-jev. Health endpoint lahko vrne 200 z bodyjem {"status": "degraded", "db": "down"} – še vedno 200, a to moraš nujno vedeti. Cenovni API lahko vrne 200 z bodyjem, kjer data.price pade na null. Iskalni API lahko vrne 200 z results: [], ker je indeks padel.

Za take primere nastavi asercijo JSON path. Nastavi pot (npr. data.status ali health.checks.db) in pričakovano vrednost (npr. healthy, true ali določeno številko). Ob vsakem preverjanju je odgovor dekodiran iz JSON, vrednost po poti je primerjana. Neujemanje konča pregled z napako, ne glede na HTTP status.

Skladnja poti je točkovna notacija z oklepaji: data.items[0].id deluje, prav tako users.john.email. Aserirana vrednost se primerja kot niz, zato "true" ustreza bool true, številke pa so skladne tako kot nizi kot številke.

Vzorci avtentikacije

Dva najpogostejša avtentikacijska vzorca delujeta takoj. Za Bearer tokene (OAuth, JWT, API ključi) uporabi polje headers: {"Authorization": "Bearer eyJhbGciOi..."}. Token ostane v nastavitvah monitorja in ga pošlje pri vsakem preverjanju. Za basic auth uporabni namenski polji uporabniško ime/geslo – shranjeni in sestavljeni v standardno glavo.

Če auth zahteva podpisovanje vsake zahteve ali obnovo žetona, je težje. Dva razumna vzorca: (1) nastavi dolgoživljenski token računa posebej za monitoring, ali (2) objavi end-point health brez avtentikacije, ki odraža stanje pravih zaščitenih, in ga nadzoruj. Večina sodobnih API-jev to že podpira iz škatle.

Priporočeni vzorci

• En monitor na ključen endpoint. Ni treba testirati vsakega – izberi 5–10 najbolj kritičnih, katerih izpad bi povzročil resno škodo.
• Uporabi točne kode. Privzete 200–399 so preveč permisivne za API-je. Endpoint za ustvarjanje naj vrne točno 201; idempotentni točno 200; prijavni endpoint točno 200 (uspeh) ali 401 (dobro oblikovan neuspeh – ne 500).
• Kombiniraj status z JSON asercijo. Skupaj ujamejo regresije transportne in vsebinske plasti. Sam status ne ujame napak v vsebini; sama JSON asercija je krhka pri preusmeritvah.
• Nastavi prag odzivnega časa. Degradacija API je zgodnji pokazatelj odvisnostnih težav. Monitor s rt_threshold_ms = 800 ti pove, da se API upočasnjuje, preden resnično pade.
• Ohrani body majhen. Preverjanje poteka vsako minuto – veliki bodyji zapravljajo pasovno širino na obeh straneh. Značilni, a minimalni payloadi so dovolj.

Poveži z drugimi tipi monitorjev

Za vsak API endpoint API monitor preverja, ali klic deluje. Posebni ping ali port monitor preverja, ali živi gostitelj. SSL/domena preverjanje na isti domeni ujame težave s certifikatom in domeno. Podmonitor DNS pazi na spremembe zapisov, ki bi kazale na zamenjavo. Štirje monitorji skupaj na en API dajo popolno sliko ob minimalnem prekrivanju.

Konfiguracija

Odpri orodje, klikni "Dodaj monitor", izberi tip "API". Prilepi URL. Odpri sekcijo Napredno. Izberi metodo, prilepi glave kot JSON, prilepi body če je potreben, nastavi basic auth če ga uporabljaš, vpiši pričakovane kode (npr. 200 ali 200,201). Dodaj asercijo JSON path, če je primerna. Nastavi interval in potrditveni prag. Shrani. Od naslednjega cikla monitor kliče tvoj API točno tako kot integrator, preveri odgovor in alarmira v sekundi ob regresiji.

Pogosta vprašanja

• Katerih HTTP metod lahko uporabljam za monitoring API?

  GET, POST, PUT, DELETE, PATCH in HEAD. Metodo nastaviš za vsak monitor posebej — za write endpoint-e (POST/PUT/PATCH) je body zahteve prav tako nastavljiv kot JSON niz ali form data.

• Kako delujejo JSON asercije?

  Navedeš JSON pot (npr. data.status ali results[0].id) in pričakovano vrednost. Monitor pridobi odziv, ga razčleni kot JSON, izloči vrednost po poti in jo primerja s pričakovano. Če se ne ujema, preverjanje pade z napako "assertion failed", ki pokaže dejansko vrednost.

• Ali lahko pošiljam glave za avtentikacijo?

  Da. Prilagojene HTTP glave so nastavljive za vsak monitor — Authorization žetoni, API ključi, content-type, karkoli. Vrednosti glav so šifrirane v mirovanju v bazi. Za Basic Auth obstaja namensko polje za uporabniško ime/geslo, ki samodejno podpiše zahtevo.

• Kaj če moj API vrne 200 z napako v podatkih?

  Pogost vzorec: API vrne HTTP 200, a body pravi {"status":"error"}. Naiven uptime monitor misli, da je vse v redu. Uporabi JSON asercijo status == "ok", da to ujameš – asercija pade in monitor poroča DOWN čeprav HTTP vrne 200.

• Kako ravnati z API-ji, ki imajo omejitev izkoriščanja (rate limit)?

  Nastavi interval preverjanj tako, da spoštuješ omejitev API-ja (npr. 5-minutni interval če API dovoljuje 12 klicev/uro). Monitor šteje en API klic na pregled iz ene regije. Preverjanja iz več regij množijo klicev — uporabi eno regijo, če ima tvoj API stroge omejitve.