API uzraudzība

Kāpēc API nepieciešama atsevišķa uzraudzība

API nav tikai lapa zem /api/. Tā ir līguma vienošanās. HTTP metode ir svarīga – GET un POST atšķiras pēc semantikas. Galvenes satur autentifikāciju, satura sarunāšanās noteikumus, idempotences atslēgas. Pieprasījuma body ir ievade. Atbildes kodam ir nozīme (401 pret 403 pret 422 – katrs nozīmē ko citu). Atbildes body ir ar noteiktu struktūru – JSON ceļi, uz kuriem paļaujas integratori. Vienkārša uptime pārbaude, kas veic tikai GET uz URL, palaidīs garām lielāko daļu veidu, kā API var avarēt: nederīgs JSON, kas vēl joprojām atgriež 200, autentifikācijas endpoints pieņem kļūdainus datus, webhook ar bojātu payload shēmu, endpoints, kas atgriež 200, bet ar "status": "error" saturā.

API uzraudzība to atrisina, dodot tev pilnu kontroli pār katru pieprasījuma un atbildes daļu. Tu konfigurē tieši tādu pieprasījumu, kādu dara tavi integratori – tā pati metode, tās pašas galvenes, tas pats body, tā pati autentifikācija – un precīzi definē, kas ir veiksmīgs rezultāts – konkrēti kodi, vērtības noteiktos JSON ceļos, atbildes laika robežas, izmēra ierobežojumi.

Pieprasījuma konfigurācija

Katrai API monitoram DiagnoSEO Uptime Monitoring vari konfigurēt:

• HTTP metode: GET, POST, PUT, PATCH, DELETE, HEAD. Izvēlies to, ko izmanto integratori.
• Pielāgotas galvenes: kā JSON objekts, piem. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Standarts OAuth, JWT, API atslēgu, content negotiation testēšanai.
• Pieprasījuma body: jebkurš virknes tips – JSON, XML, form-encoded, plain text. Nosūtāms pie POST/PUT/PATCH/DELETE.
• Basic auth: lietotājs un parole, ja endpoints ir tā aizsargāts.
• Sagaidāmie statusa kodi: saraksts vai diapazons. Noklusētie 200-399, bet vari izvēlēties tikai vienu kodu (piem., tieši 201 izveides endpointam) vai konkrētus kodus (piem., 200,202,204).

Pārbaude seko maksimums 5 novirzīšanām, atkodē gzip, parsē Content-Type, lai noteiktu JSON. Katrs pārbaudījums saglabā reālo kodu, atbildes laiku, izmēru un kļūdu, ja tāda ir. Vairāki secīgi traucējumi (pielāgojams, noklusēti 2) izraisa incidentu.

JSON path apgalvojumi

Pats statusa kods nav pietiekams daudziem API. Health endpoints var atgriezt 200 ar body {"status": "degraded", "db": "down"} – joprojām 200, bet tu vēlies to zināt. Cenu API var dot 200 ar body, kur data.price kļūst par null. Meklētāja API var atgriezt 200 ar results: [], jo indekss ir pazudis.

Šādiem gadījumiem konfigurē JSON path apgalvojumu. Iestati ceļu (piem., data.status vai health.checks.db) un gaidīto vērtību (piem., healthy, true vai konkrētu skaitli). Katras pārbaudes laikā atbilde tiek dekodēta kā JSON, un vērtība noteiktajā ceļā tiek salīdzināta. Nesakritība beidz pārbaudi ar kļūdu, neatkarīgi no HTTP statusa.

Ceļa sintakse ir punktu notācija ar iekavām: data.items[0].id darbojas, līdzīgi arī users.john.email. Apgalvotā vērtība tiek salīdzināta kā virkne, tāpēc "true" atbilst bool true, un skaitļi tiek salīdzināti gan kā virkne, gan kā skaitlis.

Autentifikācijas paraugi

Divi populārākie autentifikācijas stili darbojas uzreiz. Bearer tokeniem (OAuth, JWT, API atslēgas) izmanto headers lauku: {"Authorization": "Bearer eyJhbGciOi..."}. Tokens glabājas monitora konfigurācijā un tiek sūtīts katrā pārbaudē. Basic auth gadījumā izmanto atsevišķos lietotāja/paroles lauciņus – tie tiek glabāti un lietoti, lai automātiski izveidotu standarta galveni.

Ja autentifikācija prasa parakstīšanu katram pieprasījumam vai tokena atsvaidzināšanu, tas ir sarežģītāk. Divi saprātīgi paraugi: (1) izveido ilgi derīgu servisa konta tokenu tieši monitoringam, vai (2) nodrošini neautentificētu health endpointu, kas atspoguļo reālā aizsargātā statusu, un monitorē to. Lielākā daļa mūsdienu API jau to nodrošina pēc noklusējuma.

Ieteicamie paraugi

• Viens monitors katram kritiski svarīgajam endpointam. Nepārbaudi katru – izvēlies 5–10, kuru atteice tiešām nodarītu kaitējumu.
• Lieto precīzus kodus. Noklusējuma 200–399 ir pārāk vaļīgs API gadījumā. Izveides endpoints jāatdod tieši 201; idempotentam – tikai 200; login endpointam – tikai 200 (veiksme) vai 401 (pareizi strukturēts atteikums, nevis 500).
• Kombinē statusu ar JSON apgalvojumu. Abu kopā palīdz noķert regresijas transporta un satura līmenī. Tikai statusa kods nenosaka satura kļūdas; tikai JSON apgalvojums ir trausls novirzīšanās gadījumos.
• Uzstādi atbildes laika slieksni. API degradācija ir agrīna atkarību problēmu norāde. Monitors ar rt_threshold_ms = 800 norāda, ka API palēninās, pirms vēl viss avarē.
• Body turi mazu. Pārbaude notiek katru minūti – liels body izšķērdē datplūsmu. Pietiek ar reprezentatīviem, bet minimāliem satura piemēriem.

Kombinē ar citiem monitoringa tipiem

Katrā API endpointā API monitors pārbauda, vai izsaukums darbojas. Atsevišķs ping vai porta monitors pārbauda, vai hosts ir dzīvs. SSL/domēna pārbaude tam pašam hosta vārdam noķer sertifikāta un reģistrācijas problēmas. DNS sub-monitors uzrauga ierakstu izmaiņas, kas varētu norādīt uz pāradresāciju. Kopā četri monitori API sniedz pilnu ainu ar minimālu pārklāšanos.

Konfigurēšana

Atver rīku, klikšķini “Pievienot monitoru”, izvēlies tipu “API”. Ielīmē URL. Atver sadaļu Paplašināti. Izvēlies metodi, ielīmē galvenes kā JSON, pievieno body, ja nepieciešams, uzstādi basic auth, ja lieto, ieraksti gaidāmos kodus (piem. 200 vai 200,201). Pievieno JSON path apgalvojumu, ja nepieciešams. Uzstādi intervālu un apstiprinājuma slieksni. Saglabā. No nākamā cikla monitors izsauks tavu API tieši tāpat kā integrators, validēs atbildi un brīdinās sekundes laikā, ja parādās regresija.

Biežāk uzdotie jautājumi

• Kādas HTTP metodes varu izmantot API monitoringam?

  GET, POST, PUT, DELETE, PATCH un HEAD. Konfigurē metodi katram monitoram – rakstāmam endpointam (POST/PUT/PATCH) arī pieprasījuma body vari norādīt kā JSON virkni vai form data.

• Kā strādā JSON apgalvojumi?

  Norādi JSON ceļu (piem., data.status vai results[0].id) un gaidīto vērtību. Monitors saņem atbildi, parsē JSON, paņem vērtību ceļā un salīdzina to ar gaidīto. Ja tās neatbilst, pārbaudi neiziet ar kļūdu “assertion failed”, norādot reālo vērtību.

• Vai varu sūtīt autentifikācijas galvenes?

  Jā. Pielāgotas HTTP galvenes var norādīt katram monitoram – Authorization tokeni, API atslēgas, content-type, jebkas nepieciešams. Galveņu vērtības ir šifrētas datubāzē. Basic Auth gadījumā ir īpašs lauks lietot vārdam/parolei, kas automātiski pievieno parakstu pieprasījumam.

• Ko darīt, ja mans API atgriež 200 ar kļūdu payloadā?

  Bieža situācija: API atgriež HTTP 200, bet body satur {"status":"error"}. Naivs uptime monitors domā, ka viss ir kārtībā. Lieto JSON apgalvojumu status == "ok", lai to noķertu – apgalvojums neiziet un monitors ziņo par AVIARĒTU, pat ja HTTP kods ir 200.

• Kā rīkoties ar API, kam ir izsaukumu ierobežojums (rate limit)?

  Uzstādi pārbaudes intervālu tā, lai tas ievērotu API ierobežojumu (piem., pārbaude ik pēc 5 minūtēm, ja API atļauj 12 izsaukumus stundā). Monitors skaita vienu API izsaukumu katrai pārbaudei no katra reģiona. Multi-region pārbaudes reizinās izsaukumu skaitu – lieto single-region, ja tavā API ir stingri limiti.