API-valvonta

Miksi API tarvitsee omaa valvontaa

API ei ole pelkkä /api/-polussa oleva sivu. Se on sopimus. HTTP-metodilla on merkitystä – GET ja POST eroavat semantiikaltaan. Otsikot sisältävät todennuksen, content negotiationin, idempotenssiavaimet. Pyynnön body on syöte. Vastauskoodi on tärkeä (401 vs 403 vs 422 – jokainen kertoo eri tarinan). Vastausbodyn rakenne – JSON-polut, joihin integraattorit luottavat. Tavallinen uptime-tarkastus, joka vain käyttää GET-metodia URL:lle, missaa suurimman osan tavoista, joilla API voi kaatua: virheellinen JSON palauttaen silti 200, todennus-endpoint hyväksyy väärät tiedot, webhookilla on rikki oleva payload-skeema, endpoint palauttaa 200 mutta sisällä on "status": "error".

API-valvonta ratkaisee tämän antaen täyden kontrollin jokaiseen pyynnön osaan ja kaikkiin vastausten tarkastuksiin. Voit määrittää juuri sellaisen kutsun, jonka integraattorisi tekevät – sama metodi, samat otsikot, sama body, sama todennus – ja täsmälleen mitä onnistumisella tarkoitetaan – tarkat koodit, arvot JSON-polkujen takana, vasteajan rajat, kokorajat.

Pyynnön konfigurointi

Jokaiselle API-monitorille DiagnoSEO Uptime Monitoringissa voit määrittää:

• HTTP-metodi: GET, POST, PUT, PATCH, DELETE, HEAD. Valitse sama, jota integraattorisi käyttävät.
• Omat otsikot: JSON-objektina, esim. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. Vakiotapa testata OAuth, JWT, API-avaimia, content negotiationia varten.
• Pyynnön body: mikä tahansa string – JSON, XML, lomakekoodattu, pelkkä teksti. Lähetetään POST/PUT/PATCH/DELETE-tyyppisille pyynnöille.
• Basic auth: käyttäjätunnus ja salasana, jos endpoint on suojattu näin.
• Odotetut tilakoodit: lista tai alue. Oletuksena 200-399, mutta voit rajata tarkkaan koodiin (esim. täsmälleen 201 luonti-endpointille) tai sallia tietyt (esim. 200,202,204).

Tarkistus seuraa maksimissaan 5 uudelleenohjausta, purkaa gzipin, tulkitsee Content-Typen tunnistaakseen JSONin. Jokainen tarkastus tallentaa varsinaisen koodin, vasteajan, koon ja mahdollisen virheen. Useat peräkkäiset epäonnistumiset (määriteltävissä, oletuksena 2) luovat incidentin.

JSON path -assertiot

Pelkkä tilakoodi ei riitä monelle API:lle. Terveys-endpoint voi palauttaa 200, jonka body on {"status": "degraded", "db": "down"} – silti 200, mutta haluat ehdottomasti tietää tämän. Hintojen API voi palauttaa 200, jossa data.price on pudonnut nulliin. Hakukoneen API voi palauttaa 200, jossa results: [], koska indeksi on alhaalla.

Näitä tilanteita varten määritä JSON path -assertio. Aseta polku (esim. data.status tai health.checks.db) ja odotettu arvo (esim. healthy, true tai tietty numero). Jokaisella tarkistuksella vastaus dekoodataan JSONiksi ja arvo polun takana verrataan annettuun. Jos ei täsmää, tarkistus epäonnistuu riippumatta HTTP-statuksesta.

Polun syntaksi on piste- ja hakasuljenotaatio: data.items[0].id toimii, samoin users.john.email. Assertioarvo verrataan stringinä, joten "true" täsmää bool true-arvoon, ja numerot täsmäävät sekä stringeinä että numeroina.

Todennusmallit

Kaksi yleisintä auth-tyyliä toimii suoraan. Bearer-tunnisteille (OAuth, JWT, API-avaimet) käytä headers-kenttää: {"Authorization": "Bearer eyJhbGciOi..."}. Tokeni tallennetaan monitorin asetuksiin ja lähetetään jokaisessa tarkastuksessa. Perusautentikointiin (basic auth) käytä erikseen varattuja käyttäjätunnus/salasana-kenttiä – ne tallennetaan ja liitetään vakiomuotoiseen otsikkoon.

Jos auth vaatii per-pyyntö allekirjoitusta tai tokenin päivittämistä, se on monimutkaisempaa. Kaksi järkevää mallia: (1) määritä pitkäikäinen palvelutilin tokeni vain valvontaa varten, tai (2) luo todennusta vaatimaton health-endpoint, joka heijastaa oikean suojatun tilaa, ja valvo sitä. Useimmissa moderneissa API:ssa tämä löytyy oletuksena.

Suositellut käytännöt

• Yksi monitori per kriittinen endpoint. Älä testaa jokaista – valitse 5–10, joiden toimimattomuus aiheuttaisi oikeita ongelmia.
• Käytä tarkkoja koodeja. Oletusalue 200–399 on liian salliva API:lle. Luonti-endpointin pitäisi palauttaa tasan 201; idempotentin tasan 200; kirjautuminen tasan 200 (onnistuminen) tai 401 (muotoiltu virhe – ei 500).
• Yhdistä status ja JSON-assertio. Yhdessä ne havaitsevat regressiot sekä siirto- että sisältökerroksessa. Pelkkä status ei huomaa sisältövirheitä; pelkkä JSON-assertio on haavoittuva uudelleenohjauksissa.
• Aseta vasteaikaraja. API:n hidastuminen on usein ensimmäinen merkki riippuvuuksien ongelmista. Monitori, jolla on rt_threshold_ms = 800, kertoo että API hidastuu ennen kuin se kaatuu.
• Pidä body pienenä. Monitorointi tapahtuu minuutin välein – suuret bodyt tuhlaavat kaistaa molemmin puolin. Edustavat mutta mahdollisimman pienet payloadit riittävät.

Yhdistä muihin valvontatyyppeihin

Jokaisen API-endpointin kohdalla API-monitori tarkistaa, että kutsu toimii. Erillinen ping- tai port-monitori varmistaa, että host on elossa. Sama host-nimi SSL/domain-tarkistuksella havaitsee varmenne- ja rekisteröintiongelmat. DNS-alimonitori valvoo record-muutoksia, jotka voisivat viitata kaappaukseen. Neljä monitoria yhdessä antaa kattavan kuvan API:sta pienellä päällekkäisyydellä.

Konfigurointi

Avaa työkalu, klikkaa "Lisää monitori", valitse tyyppi "API". Liitä URL. Avaa Lisäasetukset. Valitse metodi, liitä otsikot JSONina, syötä body jos tarvitaan, lisää basic auth jos käytössä, kirjoita odotetut koodit (esim. 200 tai 200,201). Lisää JSON path -assertio tarvittaessa. Aseta väli ja vahvistuskynnys. Tallenna. Seuraavasta syklisestä lähtien monitori kutsuu API:si täsmälleen kuten integraattori tekisi, validoi vastauksen ja hälyttää sekunnin viiveellä jos tapahtuu regressio.

Usein kysytyt kysymykset

• Mitä HTTP-metodeja voin käyttää API-valvontaan?

  GET, POST, PUT, DELETE, PATCH ja HEAD. Määritä metodi per monitori — write-endpointille (POST/PUT/PATCH) myös pyynnön body on konfiguroitavissa JSON-stringinä tai form datana.

• Miten JSON-assertiot toimivat?

  Syötä JSON-polku (esim. data.status tai results[0].id) ja odotettu arvo. Monitori hakee vastauksen, jäsentää sen JSONiksi, poimii polun ja vertaa sitä odotettuun arvoon. Jos arvo ei täsmää, tarkistus epäonnistuu virheellä "assertion failed" ja näyttää todellisen arvon.

• Voinko lähettää todennusotsikoita?

  Kyllä. Mukautetut HTTP-otsikot ovat määritettävissä monitorikohtaisesti – Authorization-tokenit, API-avaimet, content-type, mitä tahansa. Otsikoiden arvot salataan lepotilassa tietokantaan. Basic Authille on oma kenttä käyttäjänimelle ja salasanalle, joka allekirjoittaa pyynnön automaattisesti.

• Entä jos API palauttaa 200 virhe-payloadilla?

  Yleinen tilanne: API palauttaa HTTP 200 mutta body sanoo {"status":"error"}. Yksinkertainen uptime-monitori luulee että kaikki on kunnossa. Käytä JSON-assertiota status == "ok" havaitaksesi tämän – assertio epäonnistuu ja monitori raportoi Häiriö, vaikka HTTP palauttaa 200.

• Kuinka käsittelen API:n rate limitin?

  Aseta tarkistuksen väli vastaamaan API:n rajoituksia (esim. 5 min väli jos API sallii 12 kutsua tunnissa). Monitori laskee yhden API-kutsun checkiä kohden yhdestä alueesta. Monialuecheckit moninkertaistavat kutsujen määrän – käytä yksittäistä aluetta jos API:llasi on tiukat rajoitukset.