Julkisissa järjestelmähankinnoissa on herätty vaatimaan avoimia rajapintoja, mikä on erittäin hyvä. Avoimet rajapinnat ovat modulaarisen arkkitehtuurin perusasioita, ja yksi keskeinen keino toimittajaloukun välttämisessä.
Mutta aika usein jää epäselväksi, mitä avoimilla rajapinnoilla tarkalleen ottaen tarkoitetaan. Ja siksi niiden hyödytkin saattavat jäädä saamatta. Siksi luonnostelimme Poikolan Antin kanssa määritelmää avoimelle rajapinnalle. Määritelmä on kommentoitavissa tässä, ja keskustelua aiheesta myös täällä ja jatkokehitetty ehdotus täällä. Tarkoitus on tämän pohjalta rakentaa virallinen määritelmä, jota esim Open Knowledge Finland ja Avointen tietojärjestelmien keskus COSS voisivat käyttää. Ja useammassakin kunnassa on myös moista määritelmää kaivattu.
Joten, tässä siis ehdotus kommentoitavaksi.
Mikä on avoin rajapinta?
Tämän dokumentin tavoitteena on määritellä selkeästi, mikä on avoin rajapinta. Täsmällistä määrittelyä tarvitaan esimerkiksi julkisissa järjestelmähankinnoissa, joissa usein vaaditaan avoimia rajapintoja. Ilman määritelmää järjestelmätoimittaja saattaa väittää, että järjestelmässä on avoin rajapinta, mutta käytännössä rajapinnan dokumentaation saa vain maksamalla tai se on saatavilla vain muutamille valituille alihankkijoille.
Perusajatuksena rajapinta on avoin, jos kuka vain voi kehittää sitä käyttävän (uuden) sovelluksen. Tähän ei riitä pelkkä dokumentaatio, vaan itse rajapintaan pitää päästä käsiksi, ja sitä vasten pitää pystyä testaamaan sovellustaan. Kehittäminen pitää voida tehdä kysymättä lupaa rajapinnan tekijältä tai haltijalta ja kertomatta etukäteen mitä on tekemässä.
Monilla julkishallinnon organisaatioilla on vahva intressi saada kaikkiin tuleviin tietojärjestelmiin kattavat rajapinnat, joilla tieto saadaan liikkumaan järjestelmien välillä nykyistä joustavammin. Rajapintojen käyttö ei sinänällään ota kantaa siihen, mikä osa tiedoista on julkisia ja mikä osa sisäisiä, mutta niiden avulla tieto on halutessa vaivattomasti saatavissa ulos järjestelmästä.
Rajapinta
Rajapinta (Application programming interface, API) on määritelmä, jonka mukaan eri ohjelmat voivat tehdä pyyntöjä ja vaihtaa tietoja eli keskustella keskenään. Käytännössä tämän dokumentin kannalta mielenkiintoiset rajapinnat ovat usein Internetin yli käytettäviä Web Service-rajapintoja. Samat periaatteet pätevät kuitenkin muunkinlaisiin toteutuksiin.
Rajapinta voi olla pelkkä datarajapinta (esim. kansalaisaloite.fi:n rajapinta) tai toiminnallinen rajapinta (esim. Helsingin Palauteytimen Open311-rajapinta, jonka kautta voi tehdä vikailmoituksia). Jos järjestelmässä on erikseen datarajapinta ja toiminnallinen rajapinta, on syytä täsmentää, minkä kaiken on tarkoitus olla avointa.
Avoin rajapinta
Jotta rajapinnan voi sanoa olevan avoin, sen täytyy täyttä seuraavat ehdot:
1. Dokumentoitu: Rajapinta on määritelty ja sen dokumentaatio on verkon kautta avoimesti saatavilla. Järjestelmän sisältämät tiedot, niiden rakenne ja rajapinnat tulee dokumentoida riittävällä tarkkuudella, jotta rajapinnan käyttöönotto ja hyödyntäminen on vaivatonta.
2. Käyttöönotettava: Avoin rajapinta on mahdollista ottaa käyttöön ilman ylläpitäjän tai järjestelmätoimittajan toimia (myös virka-ajan ulkopuolella). Mahdolliset rekisteröitymiset ym ovat automaattisia.
3. Testattava: Rajapintaa voi koekäyttää, eli tarjolla on vähintään testiaineisto.
Testattavuuden ehto voi täyttyä jollain seuraavista tavoista:
- avoin pääsy tuotantojärjestelmään, jota käyttäen palveluun voi integroitua, tai
- avoin pääsy testijärjestelmään, jossa on realistista esimerkkidataa, tai
- testijärjestelmä on ladattavissa vapaasti omaan käyttöön
Avoimen rajapinnan kautta saatava data on usein avointa, mutta sen ei tarvitse olla avointa dataa. Esimerkiksi potilastietojärjestelmä voi sisältää avoimen rajapinnan, mutta potilastiedot eivät ole avoimia.
Jos järjestelmä tarjoaa avoimen rajapinnan, se ei tarkoita, että tuotantojärjestelmään tai sen sisältämään tietoon pääsisi kuka vain käsiksi. Rajapinta voi olla avoin, vaikka tuotantojärjestelmä olisi kokonaan irti internetistä ja pääsy siihen vain hyvin rajatulla joukolla. Tällöin tarjolla pitää kuitenkin olla jonkinlainen testiympäristö.
Esimerkkejä
- Palveluun A on rajapinta tarjolla, ja palvelun toimittaja on sitoutunut tarjoamaan sen asiakkaidensa osoittamille kolmansille osapuolille -> SULJETTU
- Palvelun B datarajapintaan pääsee vapaasti käsiksi, mutta toiminnalliseen rajapintaan ei. Rajapinta on julkisesti netissä, ja esimerkkikoodia löytyy googlella -> AVOIN, mutta vain datarajapinnan osalta
- Palveluun C on olemassa toiminnallinen rajapinta. Päästäkseen siihen käsiksi täytyy pyytää käyttöavain palvelun tarjoajalta, koska palvelu ei kestäisi vapaan käytön kuormitusta. Käytännössä lupa myönnetään aina. -> SULJETTU Jos palvelusta tarjottaisiin testiversio vapaasti käytettäväksi, se olisi avoin
- Palveluun D on rajapinta, jonka määrittelyt ja dokumentaatio ovat vapaasti saatavilla. Itse palveluun ei pääse vapaasti käsiksi, koska se sisältää ihmisten henkilötietoja. Palveluntarjoaja pitää kuitenkin yllä testipalvelinta, jossa on esimerkkidataa, ja testipalvelimeen pääsee käsiksi luomalla itselleen tunnuksen palveluntarjoajan järjestelmään. -> AVOIN
Tilaajan hallitsema rajapinta
Toisinaan avoimella rajapinnalla tarkoitetaan rajapintaa, jota järjestelmän tilaajalla on oikeus käyttää ja levittää haluamallaan tavalla, mutta joka ei välttämättä ole avoimesti kenenkään muun saatavilla. Tällöin kyse ei ole avoimesta rajapinnasta, vaan olisi syytä puhua ennemmin tilaajan hallitsemasta rajapinnasta.
Tilaajan hallitsema rajapinta tarkoittaa siis rajapintaa, jonka järjestelmän tilaaja voi halutessaan avata ilman, että tähän tarvitaan järjestelmän toimittajan lupaa.
Tilaajan hallitsemalla rajapinnalla saavutetaan joitakin avoimen rajapinnan hyödyistä (erityisesti toimittajaloukun välttämäinen), mutta ei niitä kaikkia.
Huomiota ja hyviä käytäntöjä
Sopimusehdot: Tekeillä olevat JIT ehdot määrittelevät, että ostajalla pitää olla mahdollisuus halutessaan avata rajapinta (laittaa dokumentaatio ja testiaineisto verkkoon yms.) ilman, että toimittaja puuttuu siihen. JIT-ehdot eivät kuitenkaan vaadi, että kaikissa julkishallinnon ostamissa ohjelmistoissa rajapinnat olisi pakko avata, vaan tämä jää ostajan harkintaan. Käytännössä ehtoihin siis kirjataan, että rajapinta on tilaajan hallinnassa.
Standardointi: Rajapintojen toteutuksessa kannattaa suosia yleisesti käytettyjä standardeja, protokollia sekä formaatteja. Käytännössä rajapinta voidaan toteuttaa esimerkiksi REST-arkkitehtuurin mukaisesti siten, että sen kautta järjestelmän tiedot saadaan koneluettavana XML-muodossa sekä selainpohjaisia sovelluksia varten JSON-muodossa. Tässä kiteytyksessä ei oteta kantaa harmonisointiin. Harmonisointi on kuitenkin looginen kehityskulku, jotta kaikki avoimet rajapinnat eivät olisi keskenään erilaisia, vaan syntyisi ainakin toimialakohtaisesti yhteisiä käytänteitä. Open311.org on hyvä esimerkki avoimien rajapintojen standardoinnista.
Rajapinnan käyttö ilman rekisteröitymistä: Rajapinnan avoimuus ei velvoita tarjoamaan pääsyä tuotantojärjestelmään tai tuotantodataan vapaasti, vaan sen osalta voidaan vaatia esim. SLA. Jos itse tuotantojärjestelmään ei pääsyä, täytyy tarjota testijärjestelmä avoimesti kehittämistä varten.
Kuormitusrajoitukset: Avoin rajapinta kannattaa toteuttaa siten, että sitä kuormittamalla ei voi (ainakaan vahingossa) aiheuttaa uhkaa tai haittaa tietojärjestelmän muulle käytölle. Eli esimerkiksi rajapinnassa teknisesti rajattu kutsujen määrää per aikayksikkö. Tämä saattaa aiheuttaa tarpeita kahdentaa osia tietojärjestelmästä (vrt. Reittiopas).