API-felügyelet

Miért van szükség az API-nak saját monitorozásra?

Az API nem csupán egy oldal a /api/ alatt. Ez szerződés. Az HTTP metódus számít – a GET vs POST megváltoztatja a szemantikát. A fejlécek hordozzák az autentikációt, a tartalom egyeztetését, az idempotencia kulcsokat. A kérés törzse a bemenet. A válaszkód fontos (401 vs 403 vs 422 – mindegyik más történetet mesél el). A válasz törzsének szerkezete van – JSON útvonalakat használnak az integrátorok. Az egyszerű uptime ellenőrzés, amely csak GET-tel lekéri az URL-t, elszalasztja a legtöbb módot, ahogy az API elromolhat: hibás JSON, amely továbbra is 200-at ad vissza, autentikációs végpont, ami elfogad hibás adatot, webhook hibás payload séma esetén, végpont, amely 200-at ad, de belül "status": "error" szerepel.

Az API monitoring ezt megoldja, minden kérés és válasz ellenőrzési részlete felett kontrolt adva. Pontosan olyan hívást konfigurálsz, amilyet az integrátoraid végeznek – ugyanaz a módszer, ugyanazok a fejlécek, ugyanaz a törzs, ugyanaz az authentikáció – és pontosan azt, hogy mit jelent a siker – konkrét kódokat, JSON útvonalakon lévő értékeket, válaszidő küszöböket, méretkorlátokat tudsz beállítani.

Kérés konfigurációja

Minden DiagnoSEO Uptime Monitoring API monitorhoz az alábbiakat állíthatod be:

• HTTP metódus: GET, POST, PUT, PATCH, DELETE, HEAD. Válaszd azt, amelyet az integrátoraid használnak.
• Egyéni fejlécek: JSON objektumként, pl. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Alapértelmezett az OAuth, JWT, API kulcsok, content negotiation teszteléséhez.
• Kérés törzse: tetszőleges szöveg – JSON, XML, form-encoded, plain text. POST/PUT/PATCH/DELETE esetén kerül elküldésre.
• Basic auth: felhasználónév és jelszó, ha az endpoint így védett.
• Elvárt státuszkódok: lista vagy tartomány. Alapból 200-399, de leszűkítheted egy konkrét kódra (pl. pontosan 201 a létrehozási végponthoz), vagy engedélyezhetsz adottakat (pl. 200,202,204).

Az ellenőrzés legfeljebb 5 átirányítást követ, dekódolja a gzip-et, elemzi a Content-Type-ot a JSON felismeréséhez. Minden ellenőrzés rögzíti a valós kódot, választási időt, méretet és esetleges hibát. Több egymás utáni hiba (konfigurálható, alapból 2) incidenst indít.

JSON path aszerciók

Önmagában a status kódok sok API-hoz nem elegendőek. Egy health endpoint visszaadhat 200-at {"status": "degraded", "db": "down"} body-val – még mindig 200, de mindenképp tudni akarod. Egy ár API 200-at adhat vissza egy body-val, ahol data.price null-ra esett. Egy kereső API 200-at adhat vissza results: []-al, mert az index leállt.

Ilyen esetekhez állíts be JSON path aszerciót. Add meg az útvonalat (pl. data.status vagy health.checks.db) és a várt értéket (pl. healthy, true vagy konkrét számot). Minden ellenőrzésnél a válasz JSON-ból dekódolódik, az érték az útvonal alatt lesz összehasonlítva. Az eltérés a check hibájához vezet, függetlenül az HTTP státusztól.

Az útvonal szintaxisa pontozott és zárójeles: data.items[0].id működik, ugyanígy users.john.email. Az aszerciós érték sztringként kerül összehasonlításra, így a "true" illeszkedik a bool true-ra, a számok pedig megegyeznek sztringként és számként is.

Autentikáció minták

A két leggyakoribb auth stílus alapból támogatott. Bearer tokenekhez (OAuth, JWT, API kulcsok) használd a headers mezőt: {"Authorization": "Bearer eyJhbGciOi..."}. A token a monitor beállításaiban tárolódik és minden ellenőrzéshez elküldésre kerül. Basic auth esetén használd a dedikált felhasználónév/jelszó mezőt – ezek tárolódnak, és automatikusan összeállnak a szabványos fejlécbe.

Ha az authentikáció kérésenkénti aláírást vagy token frissítést igényel, bonyolultabb a helyzet. Két ésszerű minta: (1) állíts be egy hosszan élő szervizfiók tokent kifejezetten monitorozásra, vagy (2) készíts nyitott health endpointot, amely tükrözi a védett végpont státuszát, és ezt monitorozd. A legtöbb modern API ezt már alapból kínálja.

Ajánlott minták

• Végpontokra külön monitor. Nem kell mindet tesztelni – válassz 5-10-et, amelyek leállása valódi kárt okozna.
• Használj pontos kódokat. Az alap 200-399 túl engedékeny API-khoz. A létrehozó végpont adjon pontosan 201-et; idempotens pontosan 200-at; belépési végpont pontosan 200-at (siker) vagy 401-et (helyes hibakezelés – nem 500-at).
• Kombináld a státuszt JSON aszercióval. Együtt észlelik a transport és tartalom regressziókat. A státusz önmagában nem látja a tartalmi hibákat; a JSON aszerció önmagában sérülékeny átirányításoknál.
• Állíts be válaszidő küszöböt. Az API degradáció a függőségi problémák korai jele. Egy rt_threshold_ms = 800 monitor jelzi, hogy a szolgáltatás lassul, mielőtt még teljesen leállna.
• Tartsd kicsiben a body-t. Az ellenőrzés percenként fut – a nagy body fölösleges sávszélességet használ mindkét oldalon. Egy reprezentatív, de minimális payload elegendő.

Kombináld más monitor típusokkal

Minden API endpoint esetén az API monitor ellenőrzi, hogy a hívás működik. Egy külön ping vagy port monitor igazolja, hogy a kiszolgáló él. Ugyanezen hostnéven az SSL/domain ellenőrzés elkapja a tanúsítvány és regisztrációs hibákat. A DNS al-monitor figyeli a rekordváltozásokat, melyek más címre mutathatnak. Összesen négy monitor az API-ra teljes képet ad minimális átfedéssel.

Konfiguráció

Nyisd meg az eszközt, kattints a „Monitor hozzáadása” gombra, válaszd ki az „API” típust. Illeszd be az URL-t. Nyisd meg a speciális beállításokat. Válassz metódust, illeszd be fejléceket JSON-ként, törzset ha kell, állítsd be a basic auth-ot ha használod, add meg a várt kódokat (pl. 200 vagy 200,201). Adj hozzá JSON path aszerciót, ha szükséges. Állítsd be az intervallumot és a visszaigazolási küszöböt. Mentsd el. A következő ciklustól kezdve a monitor pontosan úgy hívja az API-dat, mint egy integrátor, validálja a választ, és visszaesés esetén azonnal riaszt.

Gyakran ismételt kérdések

• Milyen HTTP metódusokat használhatok API monitorozására?

  GET, POST, PUT, DELETE, PATCH és HEAD. Monitoronként állítható a metódus – író végpontokhoz (POST/PUT/PATCH) a kérés törzse is konfigurálható JSON vagy form adatként.

• Hogyan működnek a JSON aszerciók?

  Megadsz egy JSON útvonalat (például data.status vagy results[0].id) és a várt értéket. A monitor letölti a választ, JSON-ként elemzi, kinyeri az útvonalat, majd összehasonlítja az elvárttal. Ha nem egyezik, a check sikertelen lesz „assertion failed” hibával és mutatja a tényleges értéket.

• Küldhetek authentikációs fejléceket?

  Igen. Egyedi HTTP fejlécek monitoronként konfigurálhatóak – Authorization tokenek, API kulcsok, content-type stb. A fejléc értékei titkosítva vannak az adatbázisban. Basic Auth esetén van külön felhasználónév/jelszó mező, amely automatikusan aláírja a kérést.

• Mit tegyek, ha az API-m 200-at ad vissza hibás payloaddal?

  Gyakori minta: Az API HTTP 200-at ad vissza, de a body tartalma {"status":"error"}. A naív uptime monitor azt hiszi, hogy ez egészséges. Állíts be JSON aszerciót status == "ok" formában – az aszerció elbukik, a monitor DOWN-t jelent, még ha HTTP 200-at is kap.

• Mit tehetek, ha az API-mra rate limit vonatkozik?

  Állítsd be az ellenőrzési intervallumot úgy, hogy tiszteletben tartsa az API limitet (pl. 5 percenként, ha az API óránként 12 hívást enged). Egy ellenőrzés egy API hívásnak számít egy régióból. Több régióból futó ellenőrzések megszorozzák a hívások számát – használj single-regiont, ha az API-d szigorúbb limitet szab.