API stebėsena

Kodėl API reikia savo stebėsenos

API nėra tiesiog puslapis po /api/. Tai – sutartis. HTTP metodas svarbus – GET ir POST keičia semantiką. Antraštės perduoda autentifikaciją, turinio derybas, idempotencijos raktus. Užklausos body – įvestis. Atsakymo kodas svarbus (401 prieš 403 prieš 422 – kiekvienas pasakoja kitokią istoriją). Atsakymo body turi struktūrą – JSON keliai, kuriais pasitiki integratoriai. Paprasta prieinamumo patikra, kuri tik naudoja GET su URL, praleidžia daugumą būdų, kaip API gali sugesti: neteisingas JSON vis tiek su 200, autentifikacijos endpoint’as priima blogus duomenis, webhook’as su sugadintu payload’o schemu, endpoint’as grąžina 200, bet “status”: “error” viduje.

API stebėjimas tai sprendžia, suteikdamas Tau kontrolę tiek užklausos, tiek atsakymo patikros dalims. Nustatai tiksliai tokią užklausą, kokią darytų Tavo integratoriai – tas pats metodas, tos pačios antraštės, tas pats body, tas pats auth – ir tiksliai tai, kas reiškia sėkmę – konkretūs kodai, reikšmės pagal JSON kelius, atsakymo laiko ribos, dydžio ribos.

Užklausos konfigūracija

Kiekvienam API monitoriui DiagnoSEO Uptime Monitoring priemonėje gali konfigūruoti:

• HTTP metodas: GET, POST, PUT, PATCH, DELETE, HEAD. Pasirink tą, kurį naudoja integratoriai.
• Individualios antraštės: kaip JSON objektas, pvz. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Standartinis būdas testuoti OAuth, JWT, API raktus, content negotiation.
• Užklausos body: bet koks tekstas – JSON, XML, užkoduotas formoje, paprastas tekstas. Siunčiamas POST/PUT/PATCH/DELETE metu.
• Basic auth: vartotojo vardas ir slaptažodis, jei endpoint’as taip apsaugotas.
• Laukiami statuso kodai: sąrašas arba intervalas. Pagal nutylėjimą 200-399, bet gali sugriežtinti iki vieno kodo (pvz. tiksliai 201 kūrimo endpoint’ui) arba leisti konkrečius (pvz. 200,202,204).

Patikra seka iki 5 peradresavimų, dekoduoja gzip, analizuoja Content-Type, kad aptiktų JSON. Kiekviena patikra užrašo tikrą kodą, atsakymo laiką, dydį ir galimą klaidą. Daugelis iš eilės sutrikimų (konfigūruojama, pagal nutylėjimą 2) sukelia incidentą.

JSON path asercijos

Paprasčiausių statuso kodų nepakanka daugeliui API. Endpoint’o sveikata gali grąžinti 200 su body {"status": "degraded", "db": "down"} – vis dar 200, tačiau privalai apie tai žinoti. Kainų API gali grąžinti 200 su body, kur data.price tapo null. Paieškos API gali grąžinti 200 su results: [], nes indeksas sugriuvo.

Tokioms situacijoms sukonfigūruok JSON path aserciją. Nurodyk kelią (pvz., data.status ar health.checks.db) ir laukiamą reikšmę (pvz., healthy, true arba konkretaus skaičiaus). Kiekvienos patikros metu atsakymas iškoduojamas iš JSON, o reikšmė pagal kelią palyginama. Nesutapimas nutraukia patikrą sutrikimu, nepriklausomai nuo HTTP statuso.

Kelių sintaksė tai taškų, su skliausteliais, notacija: data.items[0].id veikia, kaip ir users.john.email. Asertuota reikšmė lyginama kaip tekstas, tad "true" atitinka bool true, o skaičiai tinka kaip tekstai ir kaip skaičiai.

Autentifikacijos šablonai

Du dažniausi auth stiliai veikia iš karto. Bearer tokenams (OAuth, JWT, API raktai) naudok lauką headers: {"Authorization": "Bearer eyJhbGciOi..."}. Tokenas laikomas monitoriaus konfigūracijoje ir siunčiamas prie kiekvienos patikros. Basic auth atveju naudok dedikuotus laukus vartotojo vardui/slaptažodžiui – jie saugomi ir sujungiami į standartinę antraštę.

Jei auth reikalauja pasirašymo kiekvienai užklausai ar token’o atnaujinimo, bus sudėtingiau. Dvi protingos strategijos: (1) konfigūruok ilgai galiojantį paslaugos paskyros token’ą būtent stebėjimui, arba (2) pateik neapsaugotą endpoint’ą sveikatos, kuris atspindi tikro saugomo endpoint’o statusą, ir stebėk jį. Dauguma šiuolaikinių API tai jau turi iš dėžutės.

Rekomenduojame šiuos šablonus

• Vienas monitorius vienam kritiniam endpoint’ui. Nebūkite ambicingi – pasirinkite 5–10, kurių sutrikimas reikštų realią žalą.
• Naudokite tikslius kodus. Numatyta 200-399 per daug leidžia API. Kūrimo endpoint turi grąžinti tik 201; idempotentinis tik 200; prisijungimo endpoint tik 200 (sėkmė) arba 401 (tvarkingas nesėkmės atvejis – ne 500).
• Derink statusą su JSON asercija. Kartu pagauna tiek transporto, tiek turinio regresijas. Vien statusas nesugaus turinio klaidų; vien JSON asercija trapi per peradresavimus.
• Nustatyk atsakymo laiko ribą. API degradacija dažnai iš anksto rodo priklausomybių problemas. Monitorius su rt_threshold_ms = 800 praneša, kad API lėtėja, dar iki visiško sutrikimo.
• Laikyk small body. Patikra vyksta kas minutę – dideli body eikvoja srautą abiejose pusėse. Pakanka reprezentatyvių, bet minimalių payload’ų.

Derink su kitais monitorių tipais

Kiekvienam API endpoint’ui API monitorius patikrina, ar iškvietimas veikia. Atskiras ping ar porto monitorius tikrina, ar host’as gyvas. SSL/domeno patikra tam pačiam hosto vardui pagauna sertifikatų ar registracijos problemas. Submonitorius DNS stebi įrašų pokyčius, kurie gali reikšti pakeitimą. Visi keturi monitoriai API kartu suteikia visą vaizdą su minimaliu pasikartojimu.

Konfigūracija

Atidaryk priemonę, spausk „Pridėti monitorių“, pasirink tipą „API“. Įklijuok URL. Atidaryk skyrių Išplėstiniai. Pasirink metodą, įklijuok antraštes kaip JSON, įklijuok body jei reikia, nustatyk basic auth jei naudoji, įrašyk laukiamus kodus (pvz. 200 arba 200,201). Pridėk JSON path aserciją, jei taikoma. Nustatyk intervalą ir patvirtinimo slenkstį. Išsaugok. Nuo kito ciklo monitorius iškviečia Tavo API tiksliai taip, kaip darytų integratorius, validuoja atsakymą ir praneša apie regresiją sekundės tikslumu.

Dažniausiai užduodami klausimai

• Kokius HTTP metodus galiu naudoti API stebėsenai?

  GET, POST, PUT, DELETE, PATCH ir HEAD. Konfigūruok metodą kiekvienam monitoriui atskirai — write endpoint’ams (POST/PUT/PATCH) užklausos body taip pat galima konfigūruoti kaip JSON tekstą ar formų duomenis.

• Kaip veikia JSON asercijos?

  Nurodai JSON kelią (pvz. data.status arba results[0].id) ir laukiamą vertę. Monitorius gauna atsakymą, parsuoja jį kaip JSON, išskiria kelią ir palygina su laukiamu. Jei nesutampa, patikra žlunga su klaida "assertion failed" parodydama tikrą vertę.

• Ar galiu siųsti autentifikacines antraštes?

  Taip. Individualios HTTP antraštės konfigūruojamos kiekvienam monitoriui atskirai – Authorization tokenai, API raktai, content-type, kas tik nori. Antraščių vertės duomenų bazėje šifruojamos ramybės būsenoje. Basic Auth turi atskirą lauką vartotojo vardui/slaptažodžiui, kuris automatiškai pasirašo užklausą.

• Ką daryti, jei mano API grąžina 200 su klaidos payload’u?

  Dažnas atvejis: API grąžina HTTP 200, bet body sako {"status":"error"}. Naivus uptime monitorius mano, kad tai sveika. Naudok JSON aserciją status == "ok", kad tai pastebėtum — asercija žlunga ir monitorius raportuoja DOWN net jei HTTP rodo 200.

• Kaip spręsti API rate limitą?

  Nustatyk patikrų intervalą taip, kad atitiktų API limitą (pvz. 5 min. intervalas, jei API leidžia 12 užklausų per valandą). Monitorius skaičiuoja kaip vieną API užklausą vienai patikrai iš vieno regiono. Multi-region patikros daugina užklausų skaičių – naudok single-region, jei Tavo API turi griežtus limitus.