API-integraatio selkokielellä: mitä se on, esimerkit, vaiheet ja mistä hinta muodostuu

API-integraatio tarkoittaa, että kaksi järjestelmää vaihtaa tietoa keskenään automaattisesti rajapinnan (API) kautta, ilman että kukaan kopioi tietoja käsin. Verkkokauppa lähettää tilauksen kirjanpitoon, sovellus hakee lennot varausjärjestelmästä tai lomake vie yhteydenoton asiakasrekisteriin. Integraation hinta riippuu ennen kaikkea siitä, millainen rajapinta toisessa päässä on, mihin suuntaan tieto kulkee ja kuinka paljon virhetilanteita pitää hallita. Tässä kirjoituksessa käydään läpi, mitä API ja integraatio käytännössä ovat, millaisia esimerkkejä niistä on, miten projekti etenee ja mikä vaikuttaa kustannuksiin. Esimerkit ovat tuotteista, jotka olemme rakentaneet.

Mikä on API?

API (Application Programming Interface) on sovitun muotoinen sisäänkäynti järjestelmään. Se kertoo, mitä järjestelmältä voi pyytää, missä muodossa pyyntö lähetetään ja millaisen vastauksen saa takaisin. Ajattele palvelutiskiä: et kävele varastoon itse, vaan teet tilauksen tiskillä sovitulla lomakkeella ja saat tavaran tai selityksen, miksi sitä ei ole.

Käytännössä rajapintaan kuuluu yleensä:

• dokumentaatio, josta näkee, mitä kutsuja on ja mitä ne palauttavat
• tunnistautuminen, esimerkiksi avain tai tunnukset, jotta järjestelmä tietää, kuka kysyy
• tietomuoto, nykyään useimmiten JSON, vanhemmissa ja raskaammissa järjestelmissä usein XML
• rajoitukset, kuten montako pyyntöä minuutissa saa lähettää.

Esimerkki: pyyntö ja vastaus

Kun verkkokauppa haluaa tietää tuotteen varastosaldon, se lähettää varastojärjestelmän rajapintaan pyynnön, jossa on tuotekoodi ja tunnistautumisavain. Vastaus tulee koneluettavassa muodossa: tuotekoodi, saldo ja ehkä seuraavan toimituksen päivä. Jos tuotetta ei löydy tai avain on väärä, vastaus kertoo senkin sovitulla virhekoodilla. Ihminen ei näe tätä keskustelua lainkaan; hän näkee vain verkkokaupassa oikean saldon.

Kysely vai ilmoitus?

Tietoa voi siirtää kahdella tavalla. Kyselyssä oma järjestelmä kysyy toiselta säännöllisesti tai tarpeen mukaan: onko uusia tilauksia, mikä on hinta nyt. Ilmoituksessa (webhook) toinen järjestelmä kertoo itse, kun jotain tapahtuu: maksu onnistui, tilaus peruttiin. Ilmoitus on nopeampi ja kevyempi, mutta siihen ei voi luottaa yksin, koska viesti voi myöhästyä, kadota tai tulla kahdesti. Hyvä integraatio käyttää usein molempia: ilmoitus käynnistää käsittelyn, ja tarkistuskysely varmistaa lopputuloksen.

Mitä API-integraatio tarkoittaa käytännössä

Rajapinta on vasta mahdollisuus. Integraatio on se koodi, joka käyttää sitä: se päättää, milloin tietoa haetaan tai lähetetään, muuntaa sen toisen järjestelmän ymmärtämään muotoon ja hoitaa tilanteet, joissa jokin menee pieleen. Juuri tämä viimeinen osa – virheet, aikakatkaisut, tuplapyynnöt ja vanhentuneet tiedot – erottaa demon tuotantokäyttöön kelpaavasta integraatiosta.

Tavallisia esimerkkejä:

Tilanne	Mitä integraatio tekee
Verkkokauppa ja kirjanpito tai toiminnanohjaus	Tilaukset, asiakkaat ja varastosaldot siirtyvät ilman käsityötä
Maksut	Sovellus luo maksun maksunvälittäjälle ja vahvistaa sen ennen kuin tilaus hyväksytään
Varaukset	Haku, hinnoittelu ja varaus tehdään toimittajan järjestelmään reaaliajassa
Lomake ja asiakasrekisteri	Yhteydenotto tallentuu suoraan myynnin työkaluun
Mobiilisovellus ja oma taustajärjestelmä	Sovellus hakee ja tallentaa käyttäjän tiedot palvelimelle
Tekoälyominaisuus	Sovellus lähettää tekstin tai kuvan kielimallin rajapintaan ja käsittelee vastauksen

Kaksi esimerkkiä rakentamistamme tuotteista

Flyiisi: lennot suoraan varausjärjestelmästä

Flyiisi on rakentamamme lentovarauspalvelu. Lennot tulevat matkatoimistojen käyttämästä varausjärjestelmästä. Verkkosivu ei puhu varausjärjestelmälle suoraan, vaan välissä on rakentamamme rajapinta. Varausjärjestelmä käyttää XML-muotoisia SOAP-viestejä; meidän rajapintamme hoitaa ne ja tarjoaa sivustolle selkeämmän rajapinnan, jota sivusto käyttää tyypitetyn asiakaskirjaston kautta.

Välikerros on se paikka, jossa varsinainen työ tehdään:

• Haku, hinnan tarkistus ja varaus ovat eri vaiheita. Hakutulos ei ole vielä varattava hinta, joten hinta tarkistetaan uudelleen maksuvaiheessa, ja jos tarkistus epäonnistuu, se yritetään kerran uudelleen ennen kuin asiakkaalle näytetään virhe.
• Hakutulokset välimuistissa. Tulokset tallennetaan 30 minuutiksi, jotta asiakas voi selata ja palata ilman uutta raskasta hakua.
• Vanhentunut haku. Jos hakutulosten välimuisti ehtii vanhentua, haku ajetaan uudelleen ja valittu lento löydetään sen lentonumeroiden ja lähtöpäivien perusteella, eikä asiakas joudu aloittamaan alusta.
• Liiketoiminnan säännöt yhdessä paikassa. Hinnan tarkistus ja varauspäätös tehdään rajapinnassa, ei sivuston koodissa, ja valuuttakurssit sekä lipun muutos- ja peruutusehdot tulevat sieltä asiakkaalle näytettäviksi.
• Maksut vahvistetaan palvelimella maksunvälittäjältä ennen kuin varaus etenee.

Muutokset testataan varausjärjestelmän toimittajan erillisessä testiympäristössä (pre-production) ennen kuin ne viedään tuotantoon. Tämä on tyypillistä isoille toimittajille: testiympäristö ja toimittajan vaatimusten täyttäminen kuuluvat aikatauluun ja budjettiin.

Listiq AI: yksi rajapinta verkolle, iOS:lle ja Androidille

Listiq AI ja sen Car Mods AI -sovellus toimivat verkossa, iPhonessa ja Androidissa. Kaikkia kolmea palvelee yksi taustajärjestelmä, ja natiivit iOS- ja Android-sovellukset käyttävät samaa versioitua rajapintaa (/api/v1).

Tärkein hyöty näkyy maksuissa. Käyttäjä voi ostaa krediittejä verkossa tai sovelluksessa App Storen tai Google Playn kautta, ja kaikki ostot päätyvät samaan saldoon. Sovelluskauppojen ostot tarkistetaan palvelimella ennen kuin krediitit hyvitetään, ja hyvitys on tehty niin, että sama osto ei voi hyvittyä kahdesti. Kun säännöt ovat yhdessä rajapinnassa, niitä ei tarvitse kirjoittaa kolmeen sovellukseen.

Integraatioprojektin vaiheet

1. Kartoitus. Mitkä järjestelmät yhdistetään, mitä tietoa siirtyy, mihin suuntaan ja kuinka usein? Kumpi järjestelmä on totuuden lähde, jos tiedot ovat ristiriidassa?
2. Rajapinnan selvitys. Luetaan dokumentaatio, hankitaan tunnukset ja testiympäristö ja tarkistetaan rajoitukset sekä toimittajan sopimusehdot. Tässä vaiheessa selviää usein, puuttuuko rajapinnasta jotain olennaista.
3. Tietojen yhdistäminen. Kentät ja käsitteet harvoin vastaavat toisiaan suoraan: asiakasnumero, tuotekoodi, valuutta ja aikavyöhyke pitää sopia molempiin suuntiin.
4. Toteutus. Varsinaisen tiedonsiirron lisäksi tehdään virheiden käsittely, uudelleenyritykset, aikakatkaisut ja suojaus tuplapyyntöjä vastaan. Lokeihin ei kirjoiteta henkilötietoja tai salaisuuksia.
5. Testaus. Automaattiset testit ajetaan tallennetuilla vastauksilla, jotta ne eivät riipu ulkoisesta palvelusta, ja lopuksi kokonaisuus testataan toimittajan testiympäristössä.
6. Käyttöönotto ja seuranta. Integraatiolle tehdään hälytykset: kun toinen pää ei vastaa, siitä pitää kuulla ennen asiakasta.
7. Ylläpito. Rajapinnat päivittyvät ja vanhat versiot poistuvat. Integraatio on jatkuva sopimus kahden järjestelmän välillä, ei kertatyö.

Valmis liitännäinen, integraatioalusta vai oma integraatio?

Kaikki integraatiot eivät vaadi ohjelmointia. Jos verkkokauppa-alustallesi on valmis lisäosa kirjanpito-ohjelmaasi ja se tekee sen, mitä tarvitset, se on yleensä halvin ja nopein ratkaisu. Integraatioalustat, joilla järjestelmiä yhdistetään säännöillä ilman koodia, sopivat yksinkertaisiin siirtoihin ja kokeiluihin.

Oma integraatio kannattaa, kun:

• valmista liitäntää ei ole tai se ei tue tarvittavaa toimintoa
• integraatio on osa itse palvelua, kuten varaus, maksu tai hinnoittelu
• tarvitaan omaa logiikkaa: katteita, valuuttamuunnoksia, sääntöjä tai yhdistelyä useasta lähteestä
• virhetilanteet maksavat rahaa, joten niiden käsittelyn on oltava omissa käsissä.

Mistä API-integraation hinta muodostuu

Suomesta ei löydy luotettavaa julkista hintatutkimusta tai hinnastoa, jonka perusteella ”API-integraatiolle” voisi antaa yhden hinnan. Yksinkertainen yhdensuuntainen siirto ja varausjärjestelmän integraatio ovat eri kokoluokan töitä. Hinta muodostuu näistä tekijöistä:

• Rajapinnan laatu. Hyvin dokumentoitu, moderni rajapinta testiympäristöineen on nopea käyttää. Puutteellinen dokumentaatio tai vanha tekniikka lisää selvitystyötä.
• Suunta ja reaaliaikaisuus. Yöllinen yhdensuuntainen siirto on yksinkertaisempi kuin kaksisuuntainen synkronointi, jossa molemmat päät voivat muuttaa samaa tietoa.
• Tietomallien ero. Mitä enemmän kenttiä ja käsitteitä pitää muuntaa, sitä enemmän työtä ja testattavaa.
• Virhetilanteiden hinta. Jos virhe tarkoittaa kadonnutta tilausta, tuplaveloitusta tai väärää hintaa, käsittely ja testaus pitää tehdä huolella. Maksut ja varaukset ovat tästä syystä vaativimpia.
• Toimittajan prosessi. Testiympäristö, tunnusten hankinta ja mahdollinen hyväksyntä ennen tuotantoa vievät kalenteriaikaa.
• Tietoturva ja henkilötiedot. Jos integraatio siirtää henkilötietoja, tarvitaan rajattu pääsy, salaisuuksien hallinta ja tietosuojan huomioiminen.
• Ulkoisen palvelun omat maksut. Moni rajapinta on maksullinen joko kuukausimaksulla tai käytön mukaan, ja ne ovat erillisiä kehitystyöstä.
• Ylläpito. Seuranta, päivitykset ja rajapinnan versiomuutokset kannattaa budjetoida alusta asti.

Teemme integraatioista tarjouksen projektikohtaisesti. Hyvä lähtökohta on lyhyt kuvaus: mitkä järjestelmät, mitä tietoa ja mitä sen pitäisi saada aikaan. Linkki rajapinnan dokumentaatioon nopeuttaa arviota.

Entä jos järjestelmässä ei ole rajapintaa?

Silloin vaihtoehtoja on muutama: järjestelmästä voi saada ajastetun tiedostosiirron (esimerkiksi CSV), toimittaja voi avata rajapinnan lisämaksusta, tai voi olla järkevää vaihtaa järjestelmä sellaiseen, jossa rajapinta on. Sivujen automaattista lukemista emme suosittele tuotantokäyttöön: se rikkoutuu ensimmäisestä ulkoasun muutoksesta.

Yhteenveto

API-integraatio on koodia, joka pitää kaksi järjestelmää samassa tilassa ilman käsityötä. Itse tiedonsiirto on yleensä pienin osa. Suurin osa työstä on tietojen yhdistämisessä, virhetilanteissa, testauksessa ja ylläpidossa, ja niistä myös hinta muodostuu.

Haluatko yhdistää järjestelmiä tai rakentaa rajapinnan omalle palvelullesi? Katso rajapinnat ja integraatiot, lue miten rakensimme Flyiisin, tai ota yhteyttä, niin arvioidaan, mitä integraatiosi vaatii.