API-seminaari tarjosi monipuolisen näkymän rajapintoihin

APIKA -projekti järjesti VRK:n tiloissa päivän mittaisen rajapintaseminaarin 28.1.2016. Päivän ohjelmassa oli API-talouteen liittyviä esityksiä (9 puhujaa) mutta myös kehittäjien puheenvuoroja. Osa esityksistä oli suunnattu virkahenkilöstölle, jotta saadaan nostettua API-tietoisuutta ja ymmärrystä myös julkisella sektorilla. Yksi päivän opeista onkin se, että

virkahenkilöstölle on puhuttu ja jankattu rajapinnoista eikä rajapintapalveluista. Edellinen ohjaa ajatuksen helposti vain tekniseen näkökulmaan eikä sen pitäisi olla virkahenkilön “ongelma” tai fokus.

Heidän tulisi miettiä rajapintapalveluita, jotka sisältävät teknisen toteutuksen lisäksi, palvelutason, dokumentaatiot, kehittäjäkokemuksen huomioimisen, sovittamisen osaksi isompaa kuvaa ja monia muita seikkoja.

Seminaari tuli tarpeeseen

Seminaariin osallistui paikanpäällä reilu 20 ja virtuaalisesti parhaimmillaan osallistujia oli yli 30. Vaikka MrMurphy teki kaikkensa, että päivä menisi alusta asti mönkään, saimme luovittua karikot suhteellisen kivuttomasti. Ennakkoon oli luonnollisesti laadittu ohjelma, mutta sitä muokattiin tilanteen ja osallistujien toiveiden mukaisesti päivän mittaan.

Tapahtumaan pystyi osallistumaan myös virtuaalisesti ja kaikki esitykset lähtettiin verkkoon videoneuvottelujärjestelmän läpi, joka mahdollisti puheenvuoroista keskustelun ja joustavan kysymysten esittämisen. Lista kaikista materiaaleista jutun lopussa.

Rajapintojen elinkaari metrokarttana

Päivän aloitti API-alan evankelista Kin Lane pitämällä erittäin asiantuntevan esityksen API elinkaaresta. Kin on tutkinut ja elänyt API-taloutta ja rajapintojen kehittämistä vuosia ja häntä pidetään alan ajatusjohtajana. Kin toi esiin API:en elinkaaren eri osa-alueet käyttäen hyväksi metrokartta-analogiaa ja tarjosi erittäin kattavan paketin tutkittavaa ja kahlattavaa.

Very very good presentation! Thank you @kinlane and @kyyberi for organizing this

Hänen esitystään pidettiin erittäin antoisana. Kannattaa tutustua hänen esitysmateriaaliin ja kuunnella/katsella esitys.

APIKA — avoimien rajapintojen hakemisto ja hallintajärjestelmä

Taija Björklund esitteli APIKA-ratkaisun ominaisuudet ja avasi lisäksi mahdollisia kehityspolkuja. APIKA on VRK:n toimeksiannosta käynnissä oleva avoimien rajapintojen API-hallinnan PoC. APIKA jää projektin päättyessä ylläpitoon Digipalvelutehtaaseen. APIKA löytyy osoitteesta: https://apika.digipalvelutehdas.fi/

APIKA on uudelleen brändätty ja jatkokehitetty apinf.io -palvelu. API-hallintaa on haluttu katsoa kahdesta näkökulmasta; tarjoten perinteistä API-hallintaa apien omistajille (ensivaiheessa light-versiona), ja palvella myös käyttäjiä/kehittäjiä tarjoamalla heille tarkoitettua toiminnallisuutta (esimerkiksi rajapintojen testaus) sekä auttaa kehittäjiä löytämään rajapintoja.

“APIKA alkaa olla vaivaton käyttää ja täyttää perustarpeen. Koemme erittäin tarpeelliseksi mitä digipalvelutehtaassa ja APIKAssa tehdään.” Tuukka Hastrup (kehittäjä, HSL) kertoo

API-seminaarissa syntyi paljon keskustelua APIKA:sta ja löytyi lista ominaisuuksia, joitan siihen toivottiin: metatietojen antamisen pakotus, API-avaimen käyttö pitäisi olla vapaaehtoista, linkitys API-dokumentaatioon (on roadmapilla), oman domainin käyttö (api.hsl.fi, apika.hsl.fi, umbrella.hsl.fi) ja organiaation rajapinnat kootusti (on roadmapilla) muutaman mainitakseni.

Taijan esitysmateriaali on katsottavissa verkosta samoin kuin esityksen tallenne.

6Aika rajapintamäärittelyjen kokemuksia

6Aika julkaisi pian API-seminaarin jälkeen kaksi koneluettavaa API-kuvausta Githubissa. Kuvaukset on tehty Swagger 2.0 speksin mukaan.

Ensimmäiset rajapintamääritelmät on tehty tapahtumarajapinnasta ja palauterajapinnasta. Tapahtumarajapinnan kautta julkaistaan kaupunkien tapahtumatietoja, ja palauterajapinnan kautta voi antaa kaupungille palautetta sekä hakea jo annettuja palautteita. Yhtenäiset määritelmät ovat ensi askel kohti yhtenäisiä rajapintoja, joilla helpotetaan kaupunkien avoimen datan käyttöä.

Kaupunkien avointa dataa saa kuka tahansa käyttää, yhdistellä ja jalostaa ilmaiseksi. Sen pohjalta voi luoda muun muassa visualisointeja ja sovelluksia. Tapahtumarajapinnan päälle on esimerkiksi luotu web- ja kännykkäsovelluksia, joiden avulla voi etsiä kiinnostavia tapahtumia.

Rajapintamääritelmät ovat vapaasti käytettävissä ja kommentoitavissa GitHubissa

• Tapahtumarajapinta: https://github.com/6aika/api-linked-events/blob/master/linked-events.swagger.yaml
• Palauterajapinta: https://github.com/6aika/api-palaute/blob/master/palaute.swagger.yaml

Kannattaa tutustua myös http://databusiness.fi/ sivustoon. DataBusiness.fi kerää listaa suomalaisista yrityksistä, joiden liiketoiminnassa hyödynnetään avointa dataa, löydät tietoa tapahtumista ja alan kuulumisista.

Kansallisen palveluväylän kuulumiset — liityntäkatalogi

Eero Konttaniemi VRK:sta kertoi kansallisen palveluväylän kuulumiset ja toimi tapahtuman toisena isäntänä ja tilojen tarjoajana. Rajapintojen osalta ehkä kiinnostavin osuus koski liityntäkatalogia joka on tuotannossa listaten palveluväylän rajapintapalvelut. Eeron koko esitys katsottavissa Speakerdeck palvelun kautta.

Tällä hetkellä katalogissa on vain yksi palvelu, mutta määrä lisääntyy tänä vuonna. Kannattaa siis pitää silmällä liityntäkatalogia, joka löytyy osoitteesta: api.suomi.fi ja liityntakatalogi.suomi.fi.

Viron ja Suomen yhteinen X-Road yhteisö

Viime syksystä alkaen on pikku hiljaa rakennettu Viron ja Suomen yhteistä X-Road yhteisöä. Yhteisön kuulumiset kertoi yhteisömanageri Karri Niemelä. Yhteisö on vielä tuore ja rakentaa omia käytänteitään, mutta alku on lupaava. Yhteisön Slackissa on 45 jäsentä, joista suuri osa Virosta (liity Slackiin). Mukana on X-Roadin kannalta keskeiset vaikuttajatahot kuten esimerkiksi Andres Kütt (arkkitehti) ja Heiko Vainsalu (Area Manager). Suomesta mukana on kansallisen palveluväylän kannalta keskeiset henkilöt, kuten esimerkiksi Petteri Kivimäki (järjestelmäpäällikkö). Karri toivoisi näkevänsä enemmän suomalaisia kehittäjiä ja miettii keinoja kasvattaa sekä aktivoida yhteisöä.

Yksi keskeinen elementti kasvamisessa on tietoisuus yhteisöstä ja verkkosivusto auttaa siinä asiassa. Yhteisön sivut ovatkin olleet hetken aikaa työn alla ja tulevat näinä hetkinä näkyville osoitteessa: http://community.x-road.eu/ Nimi antaa jo osviittaa siitä, että intressi ei ole rajoittaa yhteisön fokusta akselille Suomi-Viro vaan tehdä yhteisöstä globaali. Väliaikainen tietopankki yhteisöstä löytyy https://jointxroad.github.io/portal/

Yhteisön fokus ei ole rajoittunut väylän kehittämiseen vaan sisältää myös sen ympärillä olevien palveluiden kehittämisen. Karrin esitysmateriaali Speakerdeck -palvelusta.

Digitransit-rajapinta ja reittiopas

Tuukka Hastrup toi esityksesssään esiin HSL:n tekemää pitkäaikaista työtä rajapintojen kanssa. API:t ovat keskiössä siinä mitä tehdään HSL:llä ja liikennevirastossa.

Yksi Tuukan esiintuoma nouseva rajapintatyyppi on reaaliaikarajapinnat, jotka tekevät nyt tuloaan eri muodoissaan. Digitransitissa kehitetyt avoimet mqtt- ja graphql-rajapinnat ovat kaikkien testattavissa. Lisätietoja löytyy osoitteesta: digitransit.fi ja Tuukalle voi laittaa lisää kysymyksiä osoitteeseen tuukka.hastrup (at) hsl.fi. Tuukan aloitteesta lähdettiin selvittämään miten APIKA voisi tukea myös reaaliaikarajapintoja.

Tuukan API-seminaarin materiaali saatavilla Speakerdeck kautta. Lisäksi kannattaa vierailla HSL:n kehittäjäyhteisön tietovarannossa dev.hsl.fi.

Julkishallinnon API-tietoisuuden lisäämistä

Pidin oman esitykseni päivän toiseksi viimeisenä. API-seminaari oli suunnattu kehittäjille, mutta ihan yhtä lailla myös virkahenkilöstölle. Digitaalinen Suomi perustuu rajapintojen ja rajapintapalvelujen hyödyntämiseen.

Jokaisen virkahenkilön on syytä ymmärtää mikä rajapintapalvelu on, koska meidän kansallinen palveluarkkitehtuuri (väylä ja sen ympärillä olevat palvelut) perustuu niiden käyttämiseen.

Rajapinta vai rajapintapalvelu?

Mikä niiden ero sitten on? Tiivistetysti voidaan sanoa, että rajapinta on tekninen toteutus. Rajapintapalvelu sisältää sisältää paljon enemmän kuten esimerkiksi:

• kuvaus palvelusta,
• palvelutason määritys,
• dokumentaatiot,
• kehittäjäkokemuksen huomiointi ja madallus
• pääsynhallinta ja käyttäjäroolien hallinta
• elinkaarenhallinta
• selkeä versiointi

Vastaanotto tälle lähestymistavalle, tuntui uppoavan paremmin virkahenkilöstöön.

Kiitokset Jarkko ja VRK yms tämän päivä API seminaarista. Lisäsi rutkasti ymmärrystä, myös virkahenkilölle ;)

Kehittäjäkokemuksesta

Toinen asia mitä nostin esiin on kehittäjäkokemus eli developer experience (DX). Rajapintapalvelun asiakas on sovelluskehittäjä ja näin ollen kehittäjäkokemus pitää olla kehitystäohjaava arvo. Kehittäjäkokemus on menestystekijä ohjelmistokehityksessä(Fabian Fagerholm).

Miten hyvin ja helposti kehittäjä löytää rajapinnat, niiden käyttöön liittyvät tiedot/ehdot, ymmärtää rajapinnan tarkoituksen sekä miten nopeasti pääsee tekemisen alkuun

Suomi SDK

Kolmas asia jonka toin esille, on lähtöpiste “julkishallinnon kehittämiseen” eli leikkisästi Suomi SDK. Ylläolevat palvelut ovat vain esimerkkejä kehittäjille suunnatuista palveluista ja ne kaikki sijaitsevat hajallaan. Voisi olla järkevää koota tieto palveluista yhteen paikkaan ja kehittäjien kielellä ja makuisesti. Lähestymistapa asioiden esittämisessä tulee tukea kehittäjäkokemusta ja poikkeaa siten ehkä hieman muulle kansalle suunnatuista palveluista.

Voisiko olla ‘kehittäjälle’ näkymä kansallisissa palvelunäkymissä?

API-seminaarin materiaalit

Alla esitysten otsikot ja linkit materiaaleihin sekä äänityksiin.

• Kin Lane, API lifecycle webinar
• materiaali | tallenne
• Karri Niemelä, X-Road yhteisö info
• materiaali | tallenne (alkaa kohdasta 00:10:40)
• Eero Konttaniemi, Palveluväylä/liityntäkatalogi info
• materiaali | tallenne
• Taija Björklund, APIKA –palvelun tarjoama
• materiaali | tallenne (alkaa kohdasta 00:21:40)
• Vesa Härkönen, API:en vieminen APIKA palveluun, muokkaus ja asetukset
• tallenne (alkaa kohdasta 00:00:50)
• Tuukka Hastrup, Reittiopas ja Digitransit-rajapinnat APIKAssa
• materiaali | tallenne (alkaa kohdasta 00:00:57)
• Aapo Rista ja Ville Koivunen, 6Aika — rajapintojen määrittelytyön käytännöistä
• materiaali | tallenne (alkaa 00:01:00)
• Jarkko Moilanen, Mikä on API…ja vähän rajapintapalvelusta
• materiaali | tallenne (alkaa 00:31:50)
• Eero Konttaniemi, Palveluväylä detaljeina — mitä, miksi ja kenelle?
• materiaali | tallenne (alkaa 01:18:00)