Monitorizare API

De ce API-ul are nevoie de propria monitorizare

Un API nu este pur și simplu o pagină sub /api/. Este un contract. Metoda HTTP contează – GET vs POST schimbă semantica. Headerele poartă autentificarea, negocierile de conținut, chei de idempotentă. Body-ul solicitării reprezintă inputul. Codul răspunsului este important (401 vs 403 vs 422 – fiecare spune o poveste diferită). Body-ul răspunsului are structură – căile JSON pe care se bazează integratorii. O verificare simplă de uptime, care trimite doar URL-ul cu GET, ratează majoritatea modurilor în care un API poate cădea: JSON incorect care totuși returnează 200, endpoint de autentificare care acceptă date greșite, un webhook cu schemă payload stricată, endpoint care returnează 200 dar cu "status": "error" în interior.

Monitorizarea API-ului rezolvă aceste aspecte, oferindu-ți control asupra fiecărei părți a solicitării și a fiecărui punct de verificare al răspunsului. Configurezi exact același call pe care îl execută integratorii tăi – aceeași metodă, aceleași headere, același body, același auth – și exact ce înseamnă succes – coduri exacte, valori sub căi JSON, praguri de timp de răspuns, limite de dimensiune.

Configurarea solicitării

Pentru fiecare monitor API din DiagnoSEO Uptime Monitoring poți configura:

• Metoda HTTP: GET, POST, PUT, PATCH, DELETE, HEAD. Alege-o pe cea folosită de integratorii tăi.
• Headere personalizate: ca obiect JSON, ex. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Standard pentru testarea OAuth, JWT, chei API, content negotiation.
• Body-ul solicitării: orice string – JSON, XML, form-encoded, plain text. Trimis la POST/PUT/PATCH/DELETE.
• Basic auth: utilizator și parolă, dacă endpoint-ul este protejat astfel.
• Coduri de status așteptate: listă sau interval. Implicit 200-399, dar poți restrânge la un cod anume (ex. exact 201 pentru un endpoint de creare) sau permite coduri specifice (ex. 200,202,204).

Verificarea urmărește maxim 5 redirecționări, decodează gzip, parsează Content-Type pentru identificarea JSON-ului. Fiecare verificare salvează codul real, timpul de răspuns, dimensiunea și orice eroare apărută. Mai multe eșecuri consecutive (configurabil, implicit 2) declanșează un incident.

Aserțiuni JSON path

Doar codurile de status nu sunt suficiente pentru multe API-uri. Endpoint-ul health poate returna 200 cu body {"status": "degraded", "db": "down"} – tot 200, dar absolut vrei să știi asta. Un API de prețuri poate returna 200 cu body unde data.price a devenit null. Un API de căutare poate returna 200 cu results: [], deoarece indexul a căzut.

Pentru astfel de cazuri, configurează o aserțiune JSON path. Setează calea (ex. data.status sau health.checks.db) și valoarea așteptată (ex. healthy, true sau un anumit număr). La fiecare verificare, răspunsul este decodat din JSON, iar valoarea sub acea cale este comparată. Nepotrivirea duce la eșuarea verificării, indiferent de statusul HTTP.

Sintaxa căii este notație cu puncte și paranteze: data.items[0].id funcționează, la fel și users.john.email. Valoarea aserționată este comparată ca string, deci "true" corespunde cu bool true, iar numerele se potrivesc atât ca șiruri cât și ca numere.

Patternuri de autentificare

Două stiluri de autentificare sunt cele mai frecvente și funcționează direct. Pentru token-uri Bearer (OAuth, JWT, chei API) folosește câmpul headers: {"Authorization": "Bearer eyJhbGciOi..."}. Token-ul este salvat în configurația monitorului și este trimis la fiecare verificare. Pentru basic auth folosește câmpurile dedicate pentru utilizator/parolă – ele sunt stocate și combinate într-un header standard.

Dacă autentificarea are nevoie de semnare per-request sau de reîmprospătare a tokenului, este mai complicat. Două patternuri rezonabile: (1) configurează un token cu durată mare pentru un cont de serviciu folosit doar la monitoring, sau (2) expune un endpoint health neautentificat, care reflectă statusul endpoint-ului real protejat, și monitorizează-l pe acela. Majoritatea API-urilor moderne oferă deja această posibilitate out of the box.

Patternuri pe care le recomandăm

• Un monitor pentru fiecare endpoint critic. Nu testa fiecare – alege 5-10 a căror defecțiune ar însemna un prejudiciu real.
• Folosește coduri exacte. Intervalul implicit 200-399 este prea permisiv pentru API-uri. Un endpoint de creare ar trebui să returneze exact 201; unul idempotent, exact 200; endpoint-ul pentru login, exact 200 (succes) sau 401 (eșec corect – nu 500).
• Combină statusul cu aserțiunea JSON. Împreună detectează regresii la nivel de transport și conținut. Doar statusul nu detectează erorile de conținut; doar aserțiunea JSON este fragilă la redirecționări.
• Setează pragul timpului de răspuns. Degradarea API-ului este un indicator timpuriu al problemelor cu dependențele. Un monitor cu rt_threshold_ms = 800 te anunță că API-ul începe să încetinească înainte să cadă de tot.
• Menține body-ul mic. Verificarea rulează la fiecare minut – body-urile mari irosesc bandă pe ambele părți. Payload-uri reprezentative, dar minimale, sunt suficiente.

Combină cu alte tipuri de monitoare

Pentru fiecare endpoint API, monitorul API verifică dacă apelul funcționează. Un monitor separat ping sau port verifică dacă hostul e online. Verificarea SSL/domeniu pe același host detectează probleme de certificat sau înregistrare. Un submonitor DNS supraveghează schimbările de recorduri care pot indica un atac de tip redirect. Împreună, patru monitoare pe un API oferă o imagine completă cu suprapunere minimă.

Configurare

Deschide unealta, fă click pe „Adaugă monitor”, selectează tip „API”. Inserează URL-ul. Deschide secțiunea Avansat. Alege metoda, inserează headerele ca JSON, inserează body-ul dacă este necesar, setează basic auth dacă îl folosești, scrie codurile așteptate (ex. 200 sau 200,201). Adaugă o aserțiune JSON path dacă se aplică. Setează intervalul și pragul de confirmare. Salvează. De la următorul ciclu, monitorul va apela API-ul exact cum ar face un integrator, validează răspunsul și alarmează imediat la orice regresie.

Întrebări frecvente

• Ce metode HTTP pot folosi pentru monitorizarea API-urilor?

  GET, POST, PUT, DELETE, PATCH și HEAD. Configurează metoda la nivel de monitor — pentru endpoint-uri de tip „write” (POST/PUT/PATCH) și body-ul cererii poate fi configurat ca string JSON sau form data.

• Cum funcționează aserțiunile JSON?

  Indici o cale JSON (ex. data.status sau results[0].id) și valoarea așteptată. Monitorul preia răspunsul, îl parsează ca JSON, extrage calea și o compară cu valoarea așteptată. Dacă nu corespunde, verificarea eșuează cu eroarea „assertion failed”, arătând valoarea reală.

• Pot trimite headere de autentificare?

  Da. Header-ele HTTP personalizate sunt configurabile pentru fiecare monitor — token-uri Authorization, chei API, content-type, orice ai nevoie. Valorile headerelor sunt criptate în baza de date. Pentru Basic Auth există un câmp dedicat pentru user/parolă care semnează automat cererea.

• Ce se întâmplă dacă API-ul meu returnează 200 cu un payload de eroare?

  Un pattern frecvent: API-ul returnează HTTP 200 dar body-ul conține {"status":"error"}. Un monitor uptime simplu crede că totul e ok. Folosește o aserțiune JSON status == "ok" ca să detectezi asta — aserțiunea eșuează și monitorul raportează DOWN chiar dacă HTTP spune 200.

• Cum gestionez un API cu rate limit?

  Setează intervalul verificărilor astfel încât să respecți limita API-ului (ex. interval de 5 minute dacă API-ul permite 12 apeluri/oră). Monitorul numără ca un apel API per verificare dintr-un singur regiune. Verificările din mai multe regiuni multiplică numărul de apeluri — folosește single-region dacă API-ul tău are limite stricte.