API nadzor

Zašto API treba vlastiti monitoring

API nije samo stranica pod /api/. To je ugovor. HTTP metoda je bitna – GET i POST mijenjaju značenje. Zaglavlja prenose autentifikaciju, content negotiation, idempotentne ključeve. Tijelo zahtjeva je ulaz. Kod odgovora je važan (401 vs 403 vs 422 – svaki priča svoju priču). Tijelo odgovora ima strukturu – JSON putanje na koje se integratori oslanjaju. Obični uptime check, koji samo šalje GET na URL, propušta većinu načina na koje API može pasti: neispravan JSON koji svejedno vraća 200, autentifikacijski endpoint koji prihvaća pogrešne podatke, webhook s pokvarenim payload schemom, endpoint koji vraća 200 ali s "status": "error" u sadržaju.

API monitoring to rješava dajući ti kontrolu nad svakim dijelom zahtjeva i svakim dijelom verifikacije odgovora. Konfiguriraš točno onakav poziv kakav rade tvoji integratori – ista metoda, ista zaglavlja, isto tijelo, isti auth – i točno što znači uspjeh – točni kodovi, vrijednosti na JSON putanjama, pragovi vremena odgovora, granice veličine.

Konfiguracija zahtjeva

Za svaki API monitor u DiagnoSEO Uptime Monitoring možeš konfigurirati:

• HTTP metoda: GET, POST, PUT, PATCH, DELETE, HEAD. Odaberi onu koju koriste tvoji integratori.
• Vlastita zaglavlja: kao JSON objekt, npr. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Standardno za testiranje OAuth-a, JWT-a, API ključeva, content negotiation.
• Tijelo zahtjeva: bilo koji string – JSON, XML, form-encoded, plain text. Šalje se kod POST/PUT/PATCH/DELETE.
• Basic auth: korisničko ime i lozinka, ako je endpoint tako zaštićen.
• Očekivani kodovi statusa: lista ili raspon. Po defaultu 200-399, ali možeš suziti na jedan kod (npr. točno 201 za endpoint kreiranja) ili dopustiti konkretne kodove (npr. 200,202,204).

Provjera slijedi do najviše 5 preusmjeravanja, dekodira gzip, parsira Content-Type kako bi otkrila JSON. Svaka provjera bilježi stvarni kod, vrijeme odgovora, veličinu i eventualnu grešku. Više uzastopnih kvarova (konfigurabilno, po zadanim postavkama 2) pokreće incident.

JSON path asercije

Sami kodovi statusa nisu dovoljni za mnoga API-je. Health endpoint može vratiti 200 s tijelom {"status": "degraded", "db": "down"} – i dalje 200, ali to apsolutno želiš znati. Cjenovni API može vratiti 200 s tijelom gdje je data.price pao na null. Tražilica API može vratiti 200 s results: [], jer je indeks pao.

Za takve slučajeve konfiguriraj JSON path aserciju. Postavi putanju (npr. data.status ili health.checks.db) i očekivanu vrijednost (npr. healthy, true ili određeni broj). Pri svakoj provjeri odgovor se dekodira iz JSON-a, a vrijednost na putanji uspoređuje. Nepodudaranje završava check greškom, neovisno o HTTP statusu.

Sintaksa putanje koristi dotted notaciju s uglatim zagradama: data.items[0].id radi, kao i users.john.email. Asertirana vrijednost uspoređuje se kao string, tako da "true" odgovara bool true, a brojevi odgovaraju i kao string i kao broj.

Obrasci autentifikacije

Dva najčešća auth stila rade odmah. Za Bearer tokene (OAuth, JWT, API ključevi) koristi polje headers: {"Authorization": "Bearer eyJhbGciOi..."}. Token je pohranjen u podešavanju monitora i šalje se pri svakoj provjeri. Za basic auth koristiš posebno polje korisničko ime/lozinka – oni se spremaju i spajaju u standardno zaglavlje.

Ako auth traži potpisivanje svakog zahtjeva ili osvježavanje tokena, stvari su složenije. Dva razumna obrasca: (1) postavi dugovječni token servisa posebno za monitoring, ili (2) izloži neautentificirani health endpoint koji reflektira stanje pravog zaštićenog, i njega nadziraj. Većina modernih API-ja to ima već ugrađeno.

Obrasci koje preporučujemo

• Jedan monitor po kritičnom endpointu. Nema potrebe za svakim endpointom – odaberi 5-10 onih čiji bi kvar značio stvarnu štetu.
• Koristi točne kodove. Zadani 200-399 je previše permisivan za API-je. Endpoint za kreiranje treba vratiti točno 201; idempotentni endpoint točno 200; endpoint za login točno 200 (uspjeh) ili 401 (ispravan neuspjeh – ne 500).
• Kombiniraj status s JSON asercijom. Zajedno love regresije transportnog i sadržajnog sloja. Sam status ne uhvati content greške; sama JSON asercija je krhka kod redirecta.
• Postavi prag vremena odgovora. Degradacija API-ja je prvi znak problema s ovisnostima. Monitor s rt_threshold_ms = 800 javlja da API usporava, prije nego padne.
• Drži tijelo malim. Provjera ide svake minute – veliko tijelo troši bandwidth s obje strane. Reprezentativni, ali minimalni payloadovi su dovoljni.

Kombiniraj s drugim tipovima monitora

Za svaki API endpoint, API monitor provjerava radi li taj call. Odvojen ping ili port monitor provjerava da li host živi. SSL/domain check na istom host nameu hvata probleme s certifikatom i registracijom. Sub-monitor DNS prati promjene DNS zapisa koje mogu ukazivati na zamjenu. Zajedno četiri monitora na API daju potpunu sliku s minimalnim preklapanjem.

Postavljanje

Otvori alat, klikni "Dodaj monitor", odaberi tip "API". Zalijepi URL. Otvori sekciju Napredno. Odaberi metodu, zalijepi zaglavlja kao JSON, zalijepi tijelo ako treba, postavi basic auth ako ga koristiš, upiši očekivane kodove (npr. 200 ili 200,201). Dodaj JSON path aserciju, ako je primjenjivo. Postavi interval i prag potvrde. Spremi. Od sljedećeg ciklusa monitor zove tvoj API točno kao integrator, validira odgovor i alarmira na sekundu bilo kakve regresije.

Često postavljana pitanja

• Koje HTTP metode mogu koristiti za monitoring API-ja?

  GET, POST, PUT, DELETE, PATCH i HEAD. Postavi metodu za svaki monitor — za write endpointove (POST/PUT/PATCH) tijelo zahtjeva je također konfigurabilno kao JSON string ili form data.

• Kako rade JSON asercije?

  Uneseš JSON putanju (npr. data.status ili results[0].id) i očekivanu vrijednost. Monitor preuzima odgovor, parsira ga kao JSON, izvlači putanju i uspoređuje s očekivanom vrijednosti. Ako se ne podudara, check pada s greškom "assertion failed" i prikazuje stvarnu vrijednost.

• Mogu li slati zaglavlja za autentifikaciju?

  Da. Vlastita HTTP zaglavlja su prilagodljiva po monitoru — Authorization tokeni, API ključevi, content-type, što god trebaš. Vrijednosti zaglavlja su šifrirane u mirovanju u bazi. Za Basic Auth postoji posebno polje korisničko ime/lozinka koje automatski potpisuje zahtjev.

• Što ako moj API vraća 200 s error payloadom?

  Čest obrazac: API vraća HTTP 200, ali tijelo javlja {"status":"error"}. Naivan uptime monitor misli da je sve u redu. Koristi JSON aserciju status == "ok" da to uloviš – asercija pada i monitor prijavljuje DOWN iako HTTP kaže 200.

• Kako postupati s API-jem koji ima rate limit?

  Postavi interval provjera tako da poštuje limit API-ja (npr. 5-minutni interval ako API dopušta 12 poziva/sat). Monitor broji kao jedan API poziv po checku iz jedne regije. Provjere iz više regija množe pozive – koristi single-region ako tvoj API ima stroge limite.