API-rajapinta selkokielellä: mikä se on ja miten se toimii

Mikä on API eli rajapinta?

API on lyhenne sanoista Application Programming Interface. Suomeksi puhutaan ohjelmointirajapinnasta tai lyhyesti rajapinnasta. Se on ohjelman sovittu tapa antaa tietoja toiselle ohjelmalle ja ottaa niitä vastaan.

Rajapintaa voi verrata kirjaston lainaustiskiin. Asiakas ei mene hyllyille itse, vaan pyytää kirjaa tiskiltä, näyttää kirjastokortin ja saa kirjan käteensä. Samalla tavalla toinen ohjelma ei pääse suoraan verkkokaupan tai kirjanpidon tietokantaan, vaan pyytää tiedot rajapinnan kautta. Rajapinta päättää, mitä tietoja annetaan ja kenelle.

Rajapintaan liittyy muutama sana, joka toistuu ohjelmistotoimittajien puheissa:

Sana rajapinta tarkoittaa suomessa myös muuta, esimerkiksi kahden alan välistä kohtaa tai laitteiden liitäntää. Ohjelmistoista puhuttaessa se tarkoittaa käytännössä samaa kuin API.

Miten rajapinta toimii?

Rajapinnan käyttö on aina samanlainen: ohjelma lähettää pyynnön sovittuun osoitteeseen, todistaa oikeutensa avaimella ja saa vastauksen sovitussa muodossa.

12345 PyyntöOsoiteAPI-avainRajapintaVastaus

1. Pyyntö
2. Osoite
3. API-avain
4. Rajapinta
5. Vastaus

Pyyntö. Ohjelma kertoo, mitä se haluaa: esimerkiksi ”anna yrityksen tiedot y-tunnuksella 0112038-9” tai ”luo uusi asiakas näillä tiedoilla”. Pyynnöllä on aina tyyppi. Tiedon lukeminen on GET, uuden luominen POST, muuttaminen PUT tai PATCH ja poistaminen DELETE.

Osoite. Jokaisella rajapinnan toiminnolla on oma verkko-osoitteensa, samaan tapaan kuin verkkosivulla. Osoitteesta näkee usein suoraan, mitä tietoa haetaan, esimerkiksi /companies tai /invoices.

API-avain. Useimmat rajapinnat vaativat tunnisteen, jolla ohjelma todistaa oikeutensa. Avain kulkee pyynnön mukana, ja rajapinta tarkistaa sen ennen kuin antaa mitään. Avoimet julkiset rajapinnat voivat toimia ilman avainta.

Rajapinta. Järjestelmän ovi, joka ottaa pyynnön vastaan, tarkistaa oikeudet, hakee tiedot ja muotoilee vastauksen. Rajapinta päättää myös, kuinka monta pyyntöä samalta käyttäjältä otetaan vastaan minuutissa.

Vastaus. Rajapinta palauttaa pyydetyt tiedot, yleensä JSON-muodossa, tai virheilmoituksen, jos jokin meni pieleen. Vastauksen mukana tulee tilakoodi: 200 tarkoittaa onnistumista, 401 puuttuvaa tai väärää avainta, 404 sitä, ettei tietoa löytynyt, ja 429 sitä, että pyyntöjä tuli liian monta.

Esimerkki: oikea pyyntö PRH:n rajapintaan

Patentti- ja rekisterihallitus avaa yritysten perustiedot maksuttomana avoimena datana. Alla on oikea pyyntö, jonka kuka tahansa voi tehdä selaimella: osoite hakee Nokia Oyj:n tiedot y-tunnuksella.

GET https://avoindata.prh.fi/opendata-ytj-api/v3/companies
    ?businessId=0112038-9

Rajapinta vastaa JSON-muodossa. Alla on vastauksesta lyhennetty ote 20.10.2026:

{
  "totalResults": 1,
  "companies": [
    {
      "businessId": {
        "value": "0112038-9",
        "registrationDate": "1978-03-15"
      },
      "names": [
        { "name": "Nokia Oyj", "registrationDate": "1997-09-01" }
      ],
      "companyForms": [
        { "descriptions": [{ "description": "Julkinen osakeyhtiö" }] }
      ],
      "addresses": [
        { "street": "Karakaari", "buildingNumber": "7", "postCode": "02610" }
      ],
      "website": { "url": "www.nokia.com" }
    }
  ]
}

Vastauksessa on rakenne, jota ohjelma osaa lukea: y-tunnus, nimi, yhtiömuoto, osoite ja verkkosivu omissa kentissään. Ihmisen silmään se näyttää sekavalta, mutta ohjelmalle se on täsmällisempi kuin mikään taulukko.

Mihin tätä voi käyttää? Esimerkiksi verkkokaupan yritysasiakkaan lomakkeessa riittää, että asiakas kirjoittaa y-tunnuksen, ja lomake hakee nimen ja osoitteen PRH:n rajapinnasta. Silloin kirjoitusvirheet vähenevät ja laskutusosoite on oikein ensimmäisellä kerralla.

Näin kokeilet rajapintaa itse

Rajapinnan kokeilemiseen ei tarvitse ohjelmointitaitoa. Kolme helppoa tapaa:

1. Selain. Avoimen rajapinnan GET-pyynnön voi avata suoraan selaimen osoiteriville, kuten yllä olevan PRH:n osoitteen. Selain näyttää JSON-vastauksen sellaisenaan.
2. Dokumentaation kokeilunäkymä. Monen rajapinnan dokumentaatiossa on ”Try it out” -⁠painike, jolla pyynnön voi tehdä suoraan dokumentaatiosivulta ja nähdä vastauksen.
3. Integraatioalusta. Make, n8n ja Zapier osaavat tehdä rajapintapyynnön ilman koodia. Pyynnön osoite, avain ja kentät syötetään lomakkeeseen, ja vastauksen kentät näkyvät listana, josta ne voi viedä eteenpäin toiseen järjestelmään.

Kokeilu kannattaa tehdä ennen ostopäätöstä: jos dokumentaatiosta ei saa tehtyä yhtään toimivaa pyyntöä tunnissa, integraatiosta tulee kokemukseni mukaan kallis.

REST ja muut rajapintatyypit

Rajapintoja rakennetaan muutamalla eri tavalla. Yrittäjän ei tarvitse osata niitä teknisesti, mutta nimet kannattaa tunnistaa, koska ne kertovat, kuinka helppo rajapintaa on käyttää.

Rajapinnan versio kannattaa myös huomata. Esimerkissä osoitteessa on v3, eli rajapinnan kolmas versio. Kun toimittaja julkaisee uuden version, vanha suljetaan yleensä siirtymäajan jälkeen, ja integraatio pitää päivittää. Hyvä toimittaja ilmoittaa siitä etukäteen.

Kun kuulet sanan REST API, se tarkoittaa yleensä hyvää uutista: rajapinta on nykyaikainen ja sen käyttö onnistuu valmiilla työkaluilla. Webhook taas kertoo, että järjestelmä osaa ilmoittaa muutoksista itse. Siitä kerron enemmän integraatio-oppaan kohdassa, jossa käydään läpi tiedon siirtotavat.

API-avain ja tietoturva

API-avain on rajapinnan salasana. Kuka tahansa, jolla on avain, voi tehdä rajapinnan kautta kaiken, mihin avaimelle on annettu oikeudet: lukea asiakastietoja, luoda laskuja tai poistaa tilauksia.

Muutama käytäntö, jotka kannattaa vaatia jokaiselta, joka rakentaa integraatioita yrityksesi järjestelmiin:

• Oma avain jokaiselle käytölle. Kun jokaisella integraatiolla on oma avaimensa, yhden voi sulkea ilman, että muut pysähtyvät.
• Vähimmät oikeudet. Jos integraatio vain lukee tilauksia, avain ei tarvitse oikeutta poistaa niitä.
• Säilytys salaisuutena. Avain tallennetaan integraatioalustan tai palvelimen salaisuuksien säilöön, ei koodiin eikä taulukkoon.
• Yrityksen omissa nimissä. Avaimet luodaan yrityksen tunnuksilla, ei työntekijän tai konsultin henkilökohtaisella tilillä.

Toimittajat myös uusivat avaimia itse. Esimerkiksi Netvisor mitätöi vanhoja integraatioavaimia vuonna 2024, ja integraatiot piti kytkeä uudelleen. Siksi on hyvä tietää, missä avaimet ovat ja kuka ne vaihtaa.

Avoimet rajapinnat Suomessa

Suomessa moni viranomainen ja julkinen toimija tarjoaa tietojaan maksuttomina rajapintoina. Niitä voi käyttää omissa järjestelmissä ilman sopimusta, kunhan noudattaa käyttöehtoja.

Avoimista rajapinnoista on hyötyä erityisesti lomakkeissa ja raportoinnissa. Y-tunnuksella täydentyvä yritystieto, päivän valuuttakurssi laskulla tai kuljetusreitin arvio ovat pieniä asioita, jotka säästävät aikaa ja vähentävät virheitä. Digitransitin käyttöehtojen mukaan rajapintojen käytöstä ei peritä maksua, mutta käyttö vaatii rekisteröitymisen ja avaimen. Euroopan keskuspankin data-API taas toimii ilman avainta.

Mitä kysyä ohjelmistotoimittajalta?

Rajapinta kannattaa selvittää ennen kuin ostaa uuden ohjelmiston, ei vasta silloin, kun integraatiota tarvitaan. Rajapinnaton ohjelma voi sitoa yrityksen käsityöhön vuosiksi.

Esitä nämä kysymykset jokaiselle ohjelmistotoimittajalle, jonka järjestelmää harkitset:

• Onko ohjelmassa rajapinta, ja mitä tietoja sen kautta saa luettua ja kirjoitettua? Pelkkä tietojen lukeminen ei riitä, jos integraation pitää myös luoda tilauksia tai laskuja.
• Kuuluuko rajapinnan käyttö hintaan? Rajapinta voi olla vain kalleimmassa hinnoittelutasossa tai maksaa erikseen. Esimerkiksi Netvisorin hinnoitteluohjeen mukaan ohjelmistorajapinta kuuluu Professional-, Premium- ja Palkat-paketteihin.
• Onko rajapinnalla julkinen dokumentaatio? Hyvä dokumentaatio on avoimesti luettavissa ja sisältää esimerkit. Jos sitä ei saa ennen ostoa, integraatiosta tulee todennäköisesti työläs.
• Onko rajapinnalle testiympäristö? Testaus oikeilla tiedoilla on riskialtista. Testiympäristössä integraation voi rakentaa ja kokeilla turvallisesti.
• Osaako ohjelma lähettää webhookin, kun tieto muuttuu? Silloin muutokset tulevat heti eikä niitä tarvitse kysyä jatkuvasti.
• Onko rajapinnalla käyttörajoituksia? Moni rajapinta rajoittaa pyyntöjen määrää minuutissa tai päivässä. Suurilla tietomäärillä raja voi tulla vastaan.
• Onko ohjelmasta valmis liitäntä integraatioalustoihin? Valmis liitäntä Makeen, n8n:ään tai Zapieriin nopeuttaa integraatiota ja laskee sen hintaa.

Kokemukseni mukaan dokumentaatio ja testiympäristö kertovat rajapinnan laadusta eniten. Jos toimittaja ei osaa vastata näihin kysymyksiin, rajapinta on harvoin tärkeä osa heidän tuotettaan.

Esimerkki: rajapinta pk-yrityksen arjessa

Kuvitteellinen mutta tyypillinen tilanne: pieni tukkukauppa myy yritysasiakkaille verkkokaupassa, laskuttaa kirjanpito-ohjelmasta ja seuraa myyntiä asiakkuudenhallinnassa. Kaikilla kolmella ohjelmalla on REST-rajapinta.

Rajapintojen ansiosta yksi tilaus voi kulkea näin:

1. Asiakas kirjoittaa verkkokaupan lomakkeeseen y-tunnuksen, ja lomake hakee yrityksen nimen ja osoitteen PRH:n avoimesta rajapinnasta.
2. Kun tilaus maksetaan, verkkokauppa lähettää webhookin.
3. Integraatio lukee tilauksen verkkokaupan rajapinnasta ja luo siitä laskun kirjanpito-ohjelman rajapinnan kautta.
4. Sama integraatio päivittää asiakkuudenhallintaan asiakkaan viimeisimmän oston ja summan.

Jokainen vaihe käyttää rajapintaa, ja jokaisessa tarvitaan oma API-avain. Kukaan ei kopioi mitään käsin, ja tieto on kaikissa järjestelmissä sama. Miten tällainen integraatio rakennetaan ja mitä se maksaa, on integraatio-oppaan esimerkissä.

Milloin rajapinta ei riitä?

Rajapinta on edellytys integraatiolle, mutta se ei yksin siirrä mitään. Tieto liikkuu vasta, kun joku rakentaa integraation: ohjelman tai työnkulun, joka hakee tiedot yhdestä rajapinnasta ja vie ne toiseen.

Kolme tilannetta, joissa rajapinnasta huolimatta tarvitaan muuta:

• Rajapinta ei anna tarvittavia tietoja. Esimerkiksi lukuoikeus tilauksiin mutta ei tuoteriveihin. Silloin pitää kysyä toimittajalta tai käyttää tiedostosiirtoa.
• Tietojen rakenne on erilainen. Kahden järjestelmän asiakas, tuote tai lasku eivät ole samanmuotoisia. Integraatio tarvitsee muunnoksen, joka kertoo, mikä kenttä vastaa mitäkin.
• Rajapintaa ei ole lainkaan. Vanhemmista järjestelmistä tieto saadaan usein vain tiedostona. Se toimii, mutta on hitaampaa ja herkempää virheille.

Integraation toteutustavat, valmiista liitännöistä Maken ja n8n:n kaltaisiin alustoihin, sekä niiden hinnat ovat integraatio-oppaassa.

Tarkistuslista ennen ohjelmiston ostoa

Rajapinta selvitetty

0 / 6 tehty

• Ohjelmassa on rajapinta, joka antaa tarvittavat tiedot
• Rajapinnan käyttö kuuluu valittuun hinnoittelutasoon
• Rajapinnalla on julkinen dokumentaatio
• Rajapinnalle on testiympäristö
• API-avaimet luodaan yrityksen omilla tunnuksilla
• Jokaisella integraatiolla on oma avain vähimmillä oikeuksilla

Tee seuraavaksi

Pyydä toimittajalta luettelo rajapinnan kautta saatavista tiedoista. Toimittaja

Haluatko, että katson loput puolestasi? Varaa maksuton kartoitus. Tyhjennä ruksit