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).
Avoimia rajapintoja meinataan myös listata tänne (alkaen eilen, eli vielä vähän kesken) http://apisuomi.fi/
Ja tässä taas Open API Manifesto, vähän erilaisesta näkökulmasta kirjoitettuna. Ei ilmeisesti sen laajemmassa käytössä tämäkään. https://github.com/JonBou/open-API-manifesto/wiki/Manifesto-version-0
Hyvää kamaa, lisäisin myös konseptuaaliseen työkalupakkiin julkisen sektorin eventtidatan avaamisen pollaamisen sijaan pubsub rajapinnoilla, esim. avoin AMQP / JSON proxy, jolloin saadaan valmius tosiaikaisuuteen ilman kuorman liiallista kasvua tai tosiasiallista kontrollointitarvetta.
Mielestäni ei rajapintoja käsitteenä rajata vain ohjelmistokehitykseen.
Rajapinta on mikä tahansa kommunikoinnin väline (protokolla, niin sähköinen kuin manuaalinenkin) eli tarjoamalla oikeaa tavaraa, oikeassa muodossa, oikeaan aikaan sisältäen oikean tiedon oikeassa laajuudessa, niin homma lähtee pelittämään.
Manuaalisesti tämä voi olla vaikka äänestystilanne vaikka eduskuntavaaleissa. Jos on oikeellisuus kohdat täyttyvät, voidaan prosessi viedä läpi oikealla tavalla.
Sama toimii myös erilaisissa prosesseissa, oli ne sitten automatisoituja tai ei.
Eli on turhaa rajoittamista jos tässä vain puhutaan ohjelmoinnista. Avoin rajapinta on osa kaikkea toimivaa ja sujuvaa kanssakäymistä.
Rajapinnan käsitettä voi tosiaan laajentaa moneen eri kontekstiin, ja avoimuuden ajatuskin on niissä yhteyksissä hyödyllinen.
Mutta ei ole mitenkään turhaa rajautua tässä ohjelmistorajapintoihin. Päin vastoin, se on erittäin tarpeellinen rajaus, koska tavoitteena on määritellä täsmällisesti mitä avoimuus tarkoittaa ohjelmistorajapinnan tapauksessa. Tällaiselle määrittelylle on tarvetta. mm. eilen hyväksytyssä Helsingin tarkastuskertomuksessa sanotaan:
”Kaupunki on vuoden 2014 talousarvion laatimisohjeissa lähtenyt siitä vaatimuksesta, että ”Hallintokuntien tulee varmistaa uushankinnoissa sovellusten avoimet rajapinnat ja yhteensopivuudet.” Vaatimus tuli osana kaupunginhallituksen kannanottoja talousarvion 2014 raamitarkastelussa. Käytännössä vaatimuksen toteuttaminen kattavasti on kuitenkin vielä vaikeaa, koska ei ole tyhjentävää tapaa määritellä avoimia rajapintoja siten, että niitä voitaisiin käyttää tarjouspyynnössä poissulkemisperusteena tai tarjousten pisteyttämisessä.”
http://www.hel.fi/static/public/hela/Kaupunginvaltuusto/Suomi/Esitys/2014/Kanslia_2014-06-18_Kvsto_11_El/DEE26EAA-D68B-4EA7-ACB7-5CB72FE8A14B/Liite.pdf (sivu 37)
Täsmälliselle määritelmälle on siis selvä tarve, jota puhe ihmisten välisen kommunikaation tai äänestystilanteen luonteesta ei ratkaise. Siksi nyt on tarpeen rajata tämä teksti nimenomaan ohjelmistorajapintoihin.
Asian yleistys ja abstrahointi on aina uhka sekä täsmällisyydelle että ymmärrettävyydelle. Joskus on tarpeen puhua myös yksityiskohdista eikä vain suurista visioista.
Entä anonymiteetti? Onko rajapinta avoin, jos sen tarjoaja vaatii käytön vastineeksi esim. vahvasti tunnistetun identiteetin?
Tämä on muuten hyvä kysymys, johon en osaa sanoa lonkalta varmaa vastausta.
Tuotantojärjestelmään ja todelliseen dataan pääsylle vahva tunnistus voi olla hyvin perusteltua. Tiukemmatkin vaatimukset voivat joskus olla perusteltuja. Mutta pääsylle rajapinnan spesifikaatioon ja testiaineistoon se on aika kova vaatimus. Tuleeko mieleen tilannetta, jossa tuollaiselle vaatimukselle olisi jokin perusteltu ja hyvä syy?
Mielessäni on lähinnä käyttötapaus, jossa jonkin julkisen palvelun päälle rakennetaan ei-verorahoin rahoitettava businesslogiikkakerros, joka ei halua välittää asiakkaansa tietoja julkisen palvelun tuottajataholle. Ääriesimerkki (ja ilmeisen mahdoton skenaario) olisi anonymisoiva äänestysjärjestelmä, joka antaisi ulos vain lopputuloksen, eli puolueiden saamat äänimäärät ja näin syntyneet voimasuhteet eikä muuta. Vastaavasti voitaisiin tehdä anonyymiä työtä ja silti maksaa veroa, tai – jos tullaan lähemmäksi todellisia käyttötapauksia – voisin ostaa Tampereella bussilipun webistä tai maksaa siihen lisää saldoa darkcoineilla PayPunk.com palvelun kautta ilman, että joudun ensin kirjautumaan nimellä ja salasanalla Tampereen kaupungin identiteettivarastoon ennen kuin kyseinen palvelu on käytettävissä.
Sinänsä ansiokas kirjoitus avoimista rajapinnoista, jolla ei valitettavasti ole mitään merkitystä. Niin kauan kun tietojärjestelmien tietorakenteet eivät ole yhdenmukaisia ja tietosisällöt yhteismitallisia on aivan sama, ovatko rajapinnat avoimia vai eivät. Kuka tahansa metatietoa työkseen touhuava voi vahvistaa tämän väitteen. Kannustan itse kovasti avoimen lähdekoodin rajapintatoteutuksiin mutta se ei valitettavasti auta, mikäli meillä ei ole standardiformaatteja, joilla määritellään hallinnonalakohtaiset tietorakenteet, koska muuten jokainen (järjestelmätoimittaja) tekee (ja on tehnyt) oman.
Tai itse asiassa jatketaan: tekisittekö tekstin pohjalta esim. JHS-suosituksen (josta siis saadaan JHS-standardi ja valtioneuvoston asetus – eli ns. pakko) ”avoimesta rajapinnasta”? Tuskin. Miksiköhän sellaista ei ole…
JHS-suositus on työn alla. Hyvä idea, kiitos siitä.
Miksi ihmeessä emme tekisi sitä?
Mitäs mieltä raati on tästä;
http://open.epic.com/
1) Rajapinta on dokumentointu
2) Rajapinta ei vastaa todellisuutta eli suurinta osaa toiminallisuutta ei ole olemassa kuin paperilla
3) Rajapinta toimii yhteensuuntaan eli kohti epicciä mutta ei sieltä pois päin
En ihan suoralta kädeltä kykene hahmottamaan, miten luonnos taklaa ns. kirjekuorilähestymistavan käytön datarajapinnassa.
Kirjekuorilähestymistavalle tarkoitan tilannetta, jossa data siirretään teknisesti avoimessa formaatissa (XML, JSON jne.), mutta tapa, jolla sovellusaluekohtainen tieto on ”kirjekuoreen” kuvattu on esim. patentoitu ja lisensioidaan aivan muilla kuin avoimilla ehdoilla.
Ensimmäinen mieleen tuleva esimerkki tästä liittyy erääseen nimeltä mainitsemattomaan toimisto-ohjelmistojen valmistajaan, joka siirtyi käyttämään XML-pohjaista formaattia yksityisen formaatin sijasta. Tekstidokumentti talletetettiin kieltämättä XML-muodossa, mutta tapa, jolla otseikot, yksittäiset kappaleet jne. esitettiin XML-muodossa oli lujasti ko. valmistajan hyppysissä ja alussa erittäin rajoitetuilla ehdoilla käytettävissä muissa kuin ko. valmistajan ohjelmissa. Video- ja audiopuolella tämä lähestymistapa on laajasti tunnettu.
Huomio on hyvä. Määritelmän jatkokehityksessä tähän on kiinnitetty hiukan lisää huomiota: dokumentoinnin vaatimuksessa lukee nyt ”Järjestelmän sisältämät tiedot, niiden rakenne ja rajapinnat tulee dokumentoida kattavasti, jotta rajapinnan käyttöönotto ja hyödyntäminen on vaivatonta.” Formaatti saa siis olla mikä vain, mutta se pitää dokumentoida tavalla joka mahdollistaa sen hyödyntämisen.
Standardien formaattien vaatimusta emme ole ottamassa mukaan. Standardeja kyllä suositellaan painokkaasti, mutta standardien mukaisuus ei ole avoimuuden välttämätön ehto: epästandardi rajapinta on huono, mutta se voi silti olla avoin. Se vaan on huono avoin rajapinta. Mutta epästandardit formaatit pitää määritellä tarkkuudella, joka mahdollistaa niiden hyödyntämisen.
Pohdin tuota avoimen rajapinnan käsitettä kokonaisarkkitehtuurin näkökulmasta. Se avaa systemaattisesti käsitettä hiukan laajemmalle. Tein samalla pienen sovellusmatkan sote-maailmaan. ks. blogikirjoitukseni osoitteessa: http://ollintuumailut.blogspot.fi/.
Suora linkki Ollin tekstiin tulevia lukijoita varten: http://ollintuumailut.blogspot.fi/2014/07/avoin-rajapinta-sote-uudistuksen-itn-ja.html
Vähän OT mutta kuitenkin. Apotti näkyi uutisissa – Tieto on pois pelistä. Jäljellä on MUMPS- ja ei-MUMPS-vaihtoehto!!!
Auttakaa nyt kaikki lukijat Suomea pääsemään MUMPSin kahleista! Se toinen ei voi olla pahempi kuin MUMPS!
MUMPS on älyttömän laaja suljettu systeemi, jossa ei ole yhtään standardinmukaista sisäistä tai ulkoista rajapintaa. Sitten on toki siljoona sovitinta standardi- tai muutoin avoimiin rajapintoihin – niiden läpi käyttö on kuitenkin tehotonta.
Ja milläs kielellä tehdään natiivisovellukset – oma tulkittava kieli joka on ah niin joustava ja helposti kenen hyvänsä opittavissa.
Lopputulos on sitten WriteOnly -koodia. Ei kenenkään ylläpidettävissä – uusi moduuli syntyy sen sijaan helposti.
Avoimia rajapintoja ei edusta se, että sovellusten ja moduulien lähdekoodia on avoimesti saatavissa. Tällä houkuttimella MUMPS aikoinaan tuli Suomeen lähes 30 vuotta sitten.
EI ENÄÄ TOISTA 30 VUOTTA TIETOTEKNIIKAN HARHAPOLULLA – pyydän.
Kiitos Otso että olet lähtenyt määrittelemään tätä termiä. Avoin lähdekoodi ja avoin standardi on kansainvälisesti jo hyvin määritelty, mutta avointa rajapintaa ei.
Asiaa pitää kuitenkin työstää vielä. Mielestäni yllä oleva määrittelysi sekoittaa kaksi erillistä asiaa: tilaajan tarvitseman avoimuuden, jolla vältetään toimittajaloukku, ja kansalaisten tarvitseman avoimuuden, jolla mahdollistetaan avoimen datan saaminen.
Yritän osallistua kirjoittamalla määrittelyehdotelman viittaamaasi Google Docs -asiakirjaan.
Tein oman määritelmäehdotukseni tähän: https://docs.google.com/a/seravo.fi/document/d/1BbQvmPwnFObYMcD_69zXqUdm3D7VPBViaWiDOyRHK5E/edit#heading=h.kh7qazdcklu4