Tarvitaan työkaluja julkisen sektorin API-ohjaukseen

Updated: May 18, 2018

Julkisella sektorilla on API-ohjausta, mutta se tapahtuu nyt JHS suositusten kautta. JHS antaa isommat linjat ja niitä seurataan jos seurataan. JHS:t eivät riitä, koska ne ovat luonteeltaan hyvin yleisluontoisia - hajuttomia ja mauttomia. Syyskuussa 2015 laitoin liikkeelle API-manifestin kirjoittamisen ja isommalla porukalla saatiinkin se nopeasti kasaan. API-manifestin kantavana ajatuksena oli löytää joukkoistamalla 5-10 teesiä/toimenpidettä joilla edistetään API-taloutta Suomessa nyt ja tulevaisuudessa. Kumpaakin vaivaa sama vika - hajuttomuus ja mauttomuus sekä etäisyys käytännöstä.


Hötöllä on vaikea tehdä töitä. Virkamiehet, joista suurella osalla ei ole ymmärrystä rajapinnoista, niiden vaikutuksesta tai potentiaalista, tarvitsevat konkreettisia linjauksia. He tarvitsevat työkaluja asian hoitamiseen. Muussa tapauksessa lopputulos muistuttaa Sveitsiläistä linkkuveitseä - jotkut tekee korkkiruuveja, toisen hammastikkuja, osa kynsiviiloja ja suurennuslaseja. Lopputulos on sekamelska, jossa kaikille on kaikkea muttei mitenkään kohdennetusti eikä käytettävyys ole viilattu.


Inspiraationa tämän kirjoittamiselle on Jeff Bezosin "API-manifesti" Amazonilla 2002.



Ihan Bezos linjaan ei tarvitse mennä, mutta siitä voisi ottaa inspiraatiota valtionhallintoon. Bezosin linjauksella voi olettaa olevan keskeinen vaikutus siihen että Amazon on nyt API-talouden jyrä. Seuraus oli että kirjakauppa muuntui ICT alan pioneeriksi ja keskeisimmäksi palveluiden tarjoajiksi, joista parhaiten tunnetaan AWS S3, AWS EC2, AWS Lambda.‎ Nyt Amazon kiitos (API-pohjaisen) palvelukataloginsa voi siirtyä uusille markkina-alueille ketterästi ja nopeasti.


Julkisen sektorin Bezos momentin alku olisi pakottaa jokainen palvelu sisältämään vähintään yksi sisäinen rajapinta.


JHS:ien lisäksi olisi syytä ehkä olla organisaation sisäisiä voimia (suositukset/linjaukset) joilla olisi kaksi roolia: a) tarkentaa sitä mitä JHS yleisellä tasolla määrittää ja maadottaa b) toimia voimaakkaampana ohjaavana elementtinä järkevälle ja yhtenäisiä rajapintoja tuottavalle toiminnalle.

JHS:t eivät riitä, koska ne ovat luonteeltaan hyvin yleisluontoisia - hajuttomia ja mauttomia.


Valtionhallinnon toimintaympäristö

Ennen kuin voi linjata oman organisaation sisällä mitään API:en suhteen, tulee ymmärtää ympäristö, jossa organisaatio vaikuttaa; missä toimimme ja missä meidän tulee toimia sekä mitä ilmiöitä meihin vaikuttaa. 


Mikä API?

Aloitetaan siitä, että mikä on API, josta niin paljon tekniset ihmiset puhuvat. Tällä kertaa selvennetään asiaa ilman tekniikkaa tai teknologiakieltä.

Tuttavani Taija Björklund teki pyynnöstäni humaanin johdatuksen API:in:


"Paras tuntemani ja mieluiten käyttämäni analogia rajapinnalle on ravintola. Jos olet ravintolassa asiakkaana, sinulla ei ole mitään asiaa keittiöön, jossa ruokasi valmistetaan. Jotta voit saada ruokaa, sinun pitäisi kuitenkin tietää, mitä on mahdollista tilata. Tätä tarkoitusta varten ravintoloilla on ruokalista. Ruokalistan luettuasi voit tehdä tilauksesi tarjoilijalle, joka välittää tilauksen keittiöön ja tuo sinulle, mitä tilasit. Tarjoilija voi toimittaa vain sitä, mitä keittiö pystyy toimittamaan.


Miten tämä sitten liittyy rajapintoihin? Tarjoilija toimii rajapintana. Ravintolaan tullut asiakas on niin sanottu rajapinnan kuluttaja. Ruokalista dokumentoi, mitä rajapinnalta voi pyytää. Keittiö on esimerkiksi palvelin tai tietokanta, joka sisältää vain tietyntyyppistä dataa. Ravintolassakin tarjotaan vain ruokalajeja, joihin löytyy raaka-aineet, joita keittiömestari on päättänyt ravintolan tarjoavan tai joita keittiöhenkilökunta osaa valmistaa. Asiakas siis tekee pyynnön rajapinnalle opittuaan dokumentaatiosta, mitä voi pyytää ja keittiö lähettää rajapinnan kautta tilatun ruokalajin eli vastauksen. Lisäksi kun ollaan tekemisissä ihmisten kanssa olisi hyvä osata muutama taikasana, kuten ‘kiitos’ tai ‘saisinko’. Aivan samalla tavalla rajapinta odottaa sinun käyttävän tiettyjä ilmauksia, kuten vaikka ‘GET’, saadaksesi jotain."


Julkisen sektorin tietovarantoja pitää pystyä hyödyntämään mahdollisimman helposti eri palveluja rakennettaessa ja rajapinta on tähän sopiva ratkaisu. Rajapinnat ovat rakennuspalikoita palvelujen digitalisoinnille, älykaupungeille ja esineiden internetille.


Myös ei-teknisten ihmisten on ymmärrettävä edes ylätasolla, mistä puhutaan, kun puhutaan rajapinnoista. Tämä johtuu siitä, että rajapinnoista on tulossa tuotteita, ne eivät ole vain integrointivälineitä. Kun ollaan tekemisissä tuotteiden kanssa, tarvitaan muutakin kuin toteutuskykyä. Tuotteille pitää olla strategia, niitä pitää hallita, niitä tulee suunnitella ja dokumentoida. Tämän vuoksi tarvitaan laaja setti taitoja ja kokemusta. Sanomattakin on selvää että jokaisessa organisaatiossa tulisi olla riittävä määrä osaamista API:en tuotteistukseen ja hallintaan. Muussa tapauksessa hankintoja tai kehityshankkeiden ohjausta ei pysty tekemään.


Rajapinnat ovat siilojen rikkojia


VM:n lobbaama elämäntapahtumiin ja ihmiskeskeisyyteen pohjautuva filosofinen pohja vaatii toimiakseen ekosysteemejä ja alustoja - alustat toimivat rajapintojen päällä. Hallinnonalat ovat tuottaneet tietojärjestelmiä joihin ei päästetä muita. Sujuva asiakaskokemus vaatii kuitenkin tietojen yhdistämistä yli toimialarajojen. Tuotteistetut API:t ovat ratkaisu tähän. Tietojärjestelmän omistajan ei tarvitse avata koko järjestelmäänsä – vain rajapinta. Jokaiselle osapuolelle joka haluaa hyödyntää organisaatiomme keräämää tietoa ei tarvitse tehdä omaa integraatiota – avataan rajapinta kaikille. 


Tekoälyn hyödyntäminen


Suomesta ollaan tekemässä laboratoriota ja johtotähteä muun muassa tekoälyn (Aurora) osalta. Yhteiskuntamme on tähän lähes ideaali. Yksi yleinen AI:n kanssa käytetty käyttöliittymä on chatbot. Niiden tuottaminen tehokkaasti ja järkevästi edellyttää rajapintoja.

Auroran (Migri vetoinen) osalta on tiedossa että tekoälyn rakentaminen on alussa. Asiakasrajapinta (käyttöliittymä tekstin ja puheen tunnistukseen) on olemassa ja voidaan käyttää jo jossain määrin. He tarvitsevat nyt snapshot dataa, jotta tekoälyä voidaan opettaa ja testata luotua mallia ja kehikkoa. Jatkossa tavoite pitää olla API pohjainen uuden tiedon lisääminen tekoälyn käyttöön, ei vain tiedostot. AI:n toiminta perustuu aie-API:in (intention), jonka avulla käyttäjien syötteistä muodostetaan aikeita (heidän tarpeet). AI:n tarvitsema data voi olla monimuotoista, mutta sen laatu on oltava tasaista (ja korkeaa mielellään) mikäli halutaan maksimoida AI:n käyttö. 


Kansallinen palveluarkkitehtuuri ja API:t


Kansallinen palveluarkkitehtuuri perustuu Viron kanssa yhteiseen teknologiseen alustaan, vaikkakin mailla on omat instanssinsa. Palveluväylä tukee eri sektorien näkökulmasta enemmän tai vähemmän vanhentunutta SOAP teknologiaa. Tästä tulikin jo aiemmin kirjoitettua pidemmin otsikolla "SOAP jumala ja REST pakanat".


Palveluväylän kehittämisestä kummassakin maassa vastaa ja koordinoi tällä hetkellä NIIS (niis.org) ja keskusteluissa on tullut ilmi, että REST tuki on tulossa palveluväylään. Pääseekö NIIS tavoitteeseen on vielä auki ja myös sekin että kauanko menee että ratkaisu on todettu Suomessa kypsäksi ja otetaan tuotantokäyttöön. Myös se on hyvin epäselvää vielä, mitä REST tuki tarkoittaa.


Vaikka palveluväylä tulisi esimekiksi syksyllä 2018 tukemaan REST teknologiaa, on seuraavat teknologiasukupolvet jo tulossa ja niitä on jo otettu tuotantokäyttöön Suomessa myös julkisella sektorilla. Kysymysmerkiksi jää miten suomi.fi palveluväylä pysyy ajan hermolla, missä määrin se seuraa kehitystä ja mikä sen rooli on kansallisen tason API- hallintaratkaisuissa. 

Hyödyntäjät odottavat API:en käyttöönoton tapahtuvan minuuteissa.

Palveluväylä on alusta. Palveluväylässä olevien rajapintojen käyttöönotossa on käytettävyyshaasteita. Datan hyödyntäjät odottavat helppokäyttöisyyttä ja itsepalvelua. Palveluväylän kohdalla tämä romuttuu liityntäpalvelinvaatimuksella. Ennen kuin pääset hyödyntämään rajapintoja tulee asentaa liityntäpalvelin ja tehdä siihen liittyvät lupaprosessit, jotka voivat kestää viikkoja tai jopa kuukauden. Hyödyntäjät odottavat API:en käyttöönoton tapahtuvan minuuteissa. 


API:t liittyvät yhteiseen tiedonhallintaan


Yhtä lailla Suomessa on 2018 käynnissä YTI-hanke. Datan laatu ja yhteinen ymmärrys sisällästö on kriittistä. Siinä mielessä yhteiset tietomallit ovat keskiössä samoin kuin sanastot, jotka ovat koneluettavia (automatisointi). Nämä asiat ovat YTI-hankkeen keskiössä. Muun muassa tekoäly on hallituksen ohjelmassa keskeistä ja tekoäly vaatii tehokkaasti toimiakseen tasalaatuista dataa. 


Toimialan datapohjainen johtaminen


Toimialan datalähtöinen johtaminen edellyttää sujuvia ja ketteriä tietovirtojen yhdistelyjä ja käyttöä. Rajapinnoista on tullut keskeinen on nykyaikaista digitaalista palvelukehitystä, koska niiden avulla voidaan nopeuttaa ratkaisujen kehitystä merkittävästi, luoda kyvykkyyttä vastata nopeasti palvelukerroksessa esiintyviin tarpeisiin. Odottamalla tilastoja viraston politiikan ohjauksen käyttöön pahimmillaan tarkoittaa vuoden viivettä ja lisäksi joku toinen on tuottanut tilastot eikä ne ole organisaation omiin tarpeisiin ideaalit. Rajapinnat tietovarannoissa mahdollistaa datan yhdistämisen ja analysoinnin erilaisiin tarpeisiin kohtalaisin resurssein.


Näkyvissä olevia rajapintoja vaativia kehityssuuntauksia 


Myös tekoälyn laajamittainen hyödyntäminen vaatii ohjelmointirajapintoja. Näin ollen voi perustellusti sanoa, että API:en tulee oletusarvoisesti olla kehittämisen keskiössä ja välttämätön osa jokaista palvelua, joka kehitetään tai hankitaan. 


REST lähestymistapa on nyt oletusarvoinen, mutta tilanne muuttuu koko ajan. On kuitenkin erittäin todennäköistä että REST rajapinnat ovat hyödyntäjille mieluinen lähestymistapa vielä ainakin vuosia. Reaaliaikarajapinnat ovat nosteessa IoT:n tullessa yhä enemmän osaksi arkeamme. Reaaliaikarajapintojen rooli eri sektoreilla ja toimialoilla on vielä kuitenkin utuinen. 


Toinen suositummaksi nouseva teknologia on GraphQL, joka liittyy käyttöliittymien ketterään tuottamiseen. Muun muassa HSL käyttää tätä teknologiaa tuotannossa oleviessa palveluissa. HSL onkin Suomessa pioneeri API:en hyödyntämisessä. 


Huomio dataan – ei koodiin


Avoin lähdekoodi on ollut julkisella sektorilla kontrollimekanismi toimittajalukkojen estämiseen. Jatkossa sama toimii osittain. Lisäksi tulee rakentaa yhteisiä tietomalleja (vain välttämätön jottei paisu ja määrittely veny, MVP siis), joiden noudattaminen on hankintojen edellytyksenä. Tieto ja data on keskiössä, ei koodi tai järjestelmät - rajapinnat mahdollistavat tiedon sujuvan hyödyntämisen. Datan päälle järjestelmätoimittajat rakentavat rajapintoja, joiden ominaisuuksia me myös määritämme (esimerkiksi datamallit). 

Tieto ja data on keskiössä, ei koodi tai järjestelmät - rajapinnat mahdollistavat tiedon sujuvan hyödyntämisen.

Karrikoidusti sanoen meitä tulee kiinnostaa asiat seuraavassa järjestyksessä: 

  • onko rajapintoja ja jos on niin millaisia? 

  • onko graafista käyttöliittymää? 

  • onko tämä avointa lähdekoodia? 

Keskeisin API-pohjaisen ajattelun hyöty on kyvykkyys reagoida asiakastarpeisiin nopeasti ja tehokkaasti.

Haasteeksi nousee edelleen rajapintatoteutusten heterogeenisuus eli niissä kaikissa on omanlaisensa logiikka eikä standardia tapaa. API tyylioppailla voidaan ohjata kohti yhtenäisempiä ratkaisuja. Niillä on siis standardoiva vaikutus. Joka tapauksessa muutosten tekeminen rajapinnan vaihtuessa on pienempi kuin kooditason integraatioissa saati massiivisissa yhden järjestelmän kokonaisuuksissa. Keskeisin API-pohjaisen ajattelun hyöty on kyvykkyys reagoida asiakastarpeisiin nopeasti ja tehokkaasti. 


Rajapintojen asiakkaiden odotukset


Tuotetuilta rajapinnoilta odotetaan helppokäyttöisyyttä, tehokkuutta ja varmuutta. Tämä edellyttää tuoteajattelua ja tuotehallintaa sekä tuotteistusta. API ei ole vain integraatioväline tai sivutuote palvelussa. API on keskeinen osa palvelua ja väline tuottaa kansalaisille uusia digitaalisia palveluita ketterästi ja kustannustehokkaasti. 


Palveluiden rakentaminen edellyttää sektorien välistä yhteistyötä ja siinä mielessä vanhentunut teknologiapohja palveluväylässä on ongelma, koska yksityinen sektori edellyttää nykyaikaisia ratkaisuja ja teknologioita kuten esimerkiksi REST. Osa ICT –taloista on jopa kieltäytynyt tekemästä mitään SOAP pohjaista kehitystyötä. Ei tehdä enää edes rahasta. 


Esimerkkilinjauksia rajapintoihin liittyen


Yllä kuvatun toimintakentän valossa voi tehdä linjauksia rajapintojen kehittämiseen ja tarjoamiseen kumppaneille ja avoimesti kaikkien hyödynnettäväksi. 


Jokaisen kehitettävän digitaalisen palvelun tulee sisältää vähintään yksi tai useampia sisäisiä ohjelmoitirajapintoja. 

Sisäinen rajapinta ei ole kenenkään muun käytössä kuin organisaation itse. Tämä päällimmäisenä periaatteena hälventää pelkoja siitä että asioita ja mielipiteitä rajapinnasta käsitellään julkisesti esim Tivi journaalissa. Turvataan alku API-taipaleella. 

Linjauksella on arkkitehtuurin ohjausvaikutus, koska se pakottaa siirtymään kohti nykyaikaisia ratkaisuja (mikropalveluarkkitehtuuri), joissa toiminnot on eriytetty toisistaan ja sisäinen tiedonkäsittely ja vaihto tapahtuu API:en avulla. Luontevin ja yleisesti käytetty hyvä lähtökohta sisäiselle API:lle on palvelun näkyvän osan (loppuasiakkaan näkymä selaimessa) ja taustalla olevan järjestelmän välinen tiedonvaihto. 


Kaikki rajapinnat tulee kehittää pitäen silmällä mahdollisuutta, että ne avataan julkisesti joko kaikkien tai kumppanien käyttöön. 

Tämä tarkoittaa käytännössä laadukasta dokumentaatiota, kooditason käyttöesimerkkejä, yhtenäistä toteutusta ja helppoa sekä nopeaa käyttöönottoa API-hallinnan kautta. Emme pysty ennakoimaan mitkä rajapinnoista on tarpeellista avata tulevaisuudessa kumppaneille tai jopa avoimiksi (ei tarkoita avointa dataa). Sisäinen API:a on syytä kohdella kuin julkista API:a myös siitä syystä että sitä tulee hyödyntämään erilaiset ICT talot ja muut kehitystyössä käytettävät kumppanit. Hyvä tuotteistettu API hyvän dokumentaation kera nopeuttaa kehitystyötä. 


Avoimet rajapinnat – vain tunnistettuun tarpeeseen

Avoimen rajapinnan (sisältää vain avointa dataa) kautta julkaistaan lähtökohtaisesti vain tilastotietoa tai siihen rinnastettavaa anonyymia dataa eri palveluista. Avoimet rajapinnat on lisättävä myös yhteiseen API-hallintaan ja niiden käyttö edellyttää API-avainta. Datan tulee olla laadukasta - kuraa ei kukaan halua lapioida. 

Avointen rajapintojen kehittäminen edellyttää verifioitua käyttötapausta tai mieluusti useaa. Muussa tapauksessa ei tehdä. Vaihtoehtoinen avoimen datan julkaisuformaatti on tiedosto ja se tapahtuu kansallisen avoindata.fi palvelun kautta. 


Valmisohjelmistojen hankinnassa ehtona on että pääasialliset toiminnot voi suorittaa myös API:n kautta. 

Ilman API:a joudumme pitkäkestoisiin ja kalliisiin integrointiprojekteihin. Hankintailmoitukseen määritetään, mitkä palvelun toiminnallisuudet pitää pystyä tekemään API:n avulla. Poikkeukset vain perustellusti. 


Jokainen rajapinta tulee sijoittaa osaston käytössä olevaan API-hallintaratkaisuun. 

Oli sitten kyseessä sisäinen, kumppani tai julkinen API, API:t otetaan käyttöön ja käytetään vain organisaation käytössä olevan API-hallintaratkaisun kautta, ei koskaan suoraan. 

Sama koskee valmisohjelmistojen rajapintoja. Mikäli kyseessä on valmisohjelmisto, toimittaja lähtökohtaisesti vastaa tarvittavista rajapinnan tai ohjelmiston muutoksista ja niihin liittyvistä kuluista. 

Mikäli kansallinen palveluarkkitehtuuri tulee tarjoamaan tuen REST rajapinnoille ja tuen ominaisuudet ovat riittävät, ottavat organisaatiot käyttöön kansallisen ratkaisun. 


Hyödynnämme kansainvälisiä ja kansallisia standardeja API:en kehittämisessä. 

REST rajapintojen dokumentaatio pitää olla OpenAPI spesifikaation mukainen. Jokaiselle rajapinnan kutsulle (endpoint) tulee tehdä vähintään yksi kooditason kopioitava esimerkki osana dokumentaatiota.  

Käytämme kansainvälisiä ja kansallisesti määritettyjä tietomalleja elementtien ja attribuuttien nimeämisessä. Tietosisältöä määrittää kansalliset sanastot. Organisaation määrittämä API tyyliopas määrittää tarkemmin standardien käytön kaikissa tuottamisssaan rajapinnoissa. Valmisohjelmistojen rajapintojen kohdalla keskustelulla sovitaan missä määrin on välttämätöntä yhteensovittaa API tyylioppaan kanssa.


Uusien rajapintojen muotoilu ja dokumentaatio tulee arvioituttaa oman organisaation ulkopuolisilla kehittäjillä. 

Word dokumentti tai PDF tiedosto ei ole hyväksyttävä dokumentaatio. Käytämme REST rajapinnoissa koneluettavaa OpenAPI spesifikaatiota. Muiden rajapintojen osalta käytetään de factoksi muodostuneita koneluettavia kuvauksia.

Helpoiten muotoilun ja dokumentaation arviointi tapahtuu kumppaniorganisaation henkilöstöä hyväksikäyttäen. Arvioijan tulee olla sovelluskehittäjä ja arviointi tapahtuu ennen tuotantoa. Saatu palaute otettava huomioon ennen toteutusta.  

Kaikkien rajapintojen tulee noudattaa organisaation määrittämää ja julkisesti saatavilla olevaa API tyyliopasta. Poikkeuksista sovittava erikseen. Myös API:n dokumentaatio on annettava ennen käyttöönottoa ulkopuolisen tahon arvioitavaksi ja palautteen perusteella tehtävä tarvittavat muutokset ja parannukset. 

Dokumentaatio sijoitetaan käytettyyn API-hallintaratkaisuun, joka sisältää myös API-portaalin, jonka kautta sovelluskehittäjät löytävät ja käyttöönottavat organisaation rajapintoja.

0 views

©2018 by apitalisti
 

Yhteystiedot

Brändit

Apitalist is registered trademark of APInf Ltd

APIOps is registered trademark of Osaango Ltd and APInf Ltd

Tilaa kirja

API -talous 101 -kirja Alma Talent kaupassa!

Podcast

"Opi tuntemaan API -asiakkaasi" podcast -sarja

Lue lisää!