Yhteenveto

Tieto on nykyaikaisten palvelujen merkittävä raaka-aine. Maailman eniten arvoa tuottavat yritykset hyödyntävät tietoa tehokkaasti. Myös uudet liiketoimintamallit perustuvat yhä useammin tiedon tehokkaaseen hyödyntämiseen palveluprosesseissa. Suomen talouskasvua ja tuottavuutta on mahdollista auttaa edistämällä tiedon tehokasta hyödyntämistä sekä teknologian että lainsäädännön keinoin.

Ohjelmointirajapinta (Application programming interface, API) määrittelee, miten ohjelmisto tarjoaa tietoja tai palveluita sovelluksille tai muille tietojärjestelmille. Siinä missä graafinen selaimeen perustuva käyttöliittymä kuten esimerkiksi suomi.fi palvelee ihmisiä, koneluettava rajapinta palvelee järjestelmiä ja ohjelmistoja.

Uudet rajapintoihin perustuvat liiketoimintamallit korvaavat vanhoja. Rajapintojen avulla liiketoimintaekosysteemien skaalaus on kaikista tehokkainta ja sen seuraksena syntyy API-talous ('API Economy'). Silloin kun API:en tekemiseen käytetään julkista rahaa, niin on ajateltava myös liiketoimintamallia. Tulisi olla läsnä ajatus siitä, millaista liiketoimintamallia julkaistava API tukee. Jos liiketoimintamallia ei tunnisteta tai se on hyvin geneerinen, niin silloin on mietittävä uudemman kerran kannattaako API:n julkaisuun ja ylläpitoon laittaa rahaa, vai olisiko kyseinen raha hyödyllisemmin käytetty jossain muualla. Toisaalta voi aloittaa API:n tekemisen sillä, että kertoo aikeestaan ja katsoo onko mistään suunnasta vastakaikua, omasta piiristä voi olla hankala nähdä kaikkea potentiaalia.

Julkinen sektori ainakin pyrkii pienentämään kulujaan koko ajan. Tämä yhdistettynä rajapintojen laajaan hyödyntämiseen avaa yksityiselle sektorille uusia mahdollisuuksia osallistua julkisen sektorin palvelutuotantoon. Suomessa julkisen sektorin "Once Only" periaatetta ei voida kustannustehokkaasti soveltaa ilman laadukkaita rajapintoja.

API-manifesti

Versio 1.1 - 26.4.2016

Mikä API-manifesti?

API-manifestin tarina alkoi syyskuussa 2015, kun Jarkko Moilanen käynnisti API-yhteisössä keskustelun API-strategiasta, jonka kantavana ajatuksena oli löytää joukkoistamalla 5-10 teesiä/toimenpidettä joilla edistetään API-taloutta Suomessa nyt ja tulevaisuudessa. Ehdotuksia teeseiksi sai ehdottaa kuka tahansa avoimessa hackpadissa.

7 teesiä API-talouden edistämiseen Suomessa nyt ja tulevaisuudessa.

Sen jälkeen kokoonnuimme Väestörekisterikeskuksessa 20.10.2015 miettimään tarkemmin miten edetä ja mihin suuntaan. Päädyimme strategian kirjoitamisen sijasta työstämään API-manifestia. Mika Honkanen valittiin pääeditoriksi ja työskentelyä jatkettiin kaikille avoimessa digipalvelutehtaan hackpadissa.

API-manifestin työstö jatkui hackpadissa ja pääosa keskustelusta käytiin API:Suomi Facebook -ryhmässä. Joulukuussa manifesti siirrettiin API:suomi -yhteisön Githubiin ja kehitys jatkui sen jälkeen Github issue-listoja hyväksikäyttäen. Joulukuun viimeisenä päivänä 30.12.2015 julkaistiin ensimmäinen versio API-manifestista. Työ jatkuu edelleen ja jatkokehitys sekä kontribuutiot otetaan vastaan Githubissa.

1. Palvele digitaalisesti rajapintapalvelun avulla

Suunnittele tietotekniikkaan pohjautuva digitaalinen palvelu- ja ohjelmistokehitys aloittaen rajapinnan suunnittelusta. Kaikki tietokoneohjelmat siirtävät tietoa rajapintojen läpi. Rajapintoihin pohjautuvassa taloudessa (engl. API Economy) on tavoitteena palvella rajapintojen avulla sidosryhmiä sähköisesti mahdollisimman hyvin sekä organisaation sisä- että ulkopuolella. Siinä rajapinta nostetaan digitaalisen toiminnan keskiöön ja se nähdään tapana palvella digitaalisesti mahdollisimman hyvin.

Toimivat rajapinnat ovat edellytys digitaalisten ekosysteemien luomiselle ja skaalaamiselle.

Rajapinnat tuovat digitaalisille palveluille lisäarvoa ja mahdollistavat toiminnan ketteryyden. Varmista, että rajapinnalla on riittävä palvelulupaus (engl. Service-Level Agreement, SLA) ja laita palvelulupaus julkisesti nähtäville. Rajapintapalvelun kannalta on tärkeää, että sen tarjoama rajapinta sekä toiminnallisesti luotettava että tietoturvallinen. Kehittäjille pitää tarjota riittävä luotettavuus rajapinnan toiminnalle ja olemassaololle, jotta kehittäjät kiinnostuvat rajapinnasta.

Aiemmin oli tärkeää luoda organisaatiolle internetsivut. Vuosien aikana päätelaitteiden (tietokoneet, kännykät, tabletit, jääkaapit, stereot, nettitelevisiot) määrä ja erilaiset ominaisuudet monipuolistuvat. Nykyään on tärkeää tarjota mahdollisimman hyvä & avoin rajapinta, jonka päälle sidosryhmät voivat rakentaa erilaisia käyttöliittymiä & käyttökokemuksia. Sidosryhmät voivat jalostaa rajapinnan tarjoamaa tietoa mitä erilaisimmin tavoin. Toimivan rajapinnan avulla teknologian ja toimintaympäristön muutoksiin on helpompi reagoida nopeammin.

2. Suosi avoimuutta

Avoimuus tuottaa tutkitusti parempaa laatua nopeammin. Avoimuuden avulla palvellaan paremmin ja ketterämmin. Sisällön avoin lisenssi mahdollistaa innovoinnin ja uudelleenkäytön myös liiketoiminnassa. Avoin rajapinta tekee sen takana olevan sisällön käytöstä helpompaa. Sisällytä tietojärjestelmähankintoihin avoin rajapinta aina kun mahdollista. Katso avoimen rajapinnan määritelmä osoitteesta: http://avoinrajapinta.fi.

3. Tee käyttöönotosta mahdollisimman helppoa

Laatu tarkoittaa myös hyvää saavutettavuutta. Rajapinnan kohdalla sillä tarkoitetaan sekä helppoa löydettävyyttä että käytettävyyttä. Laadukkaan rajapinnan käytön oppii mahdollisimman nopeasti. Hyvällä rajapinnalla on hyvä ajantasainen dokumentaatio, jonka löytää helposti. Hyvässä dokumentaatiossa on myös runsaasti tapaus- ja koodiesimerkkejä rajapinnan hyödyntämisestä.

Käytä kehittäjäportaalia kokoamaan materiaali helposti saavutettavaksi, mielekkääksi kokonaisuudeksi.

Muita keinoja parantaa kehittäjäkokemusta ovat muun muassa kehitysympäristöt, rajapintaluettelot, automatisoitu API-avaimien luominen (käytön seurantaa varten) sekä palautekanava rajapinnan omistajan ja kehittäjän välillä. Palautekanavaksi suositellaan jotain avointa, viestit arkistoivaa foorumia. Käytä kehittäjäportaalia kokoamaan materiaali helposti saavutettavaksi, mielekkääksi kokonaisuudeksi. Edellä mainitut asiat sisältävästä kokonaisuudesta käytetään nimeä rajapintapalvelu. Tue rajapinnan päälle rakentavaa kehittäjää eri tavoin mahdollisimman kattavasti. Esimerkiksi puhelinpalvelu (arkisin kello 9-16), wiki ja sähköposti (alle 3 päivän vastaustakuulla) ovat hyviä tapoja tukea ja huokutella kehittäjiä..

Uusi käyttäjä pystyy ottamaan parhaimmat rajapintapalvelut käyttöön alle viidessä (5) minuutissa. Rajapinnat on luotettavia (ei käyttökatkoja) ja niiden kehitys/olemassa olo on avattu vuosiksi eteenpäin. Yksi suurimmista ongelmista rajapinnoissa on edelleen se, että niiden käyttöönotto kokeilemisen avulla vie aikaa, kun niitä käsittelevä dokumentaatio on puutteellista. Hyvässä dokumentaatiossa tarjotaan eri tarpeisiin valmiita ja toimivia esimerkki-koodeja rajapintakyselyihin (esimerkiksi Python & javascript), joita voi sitten lähteä kehittämään eteenpäin, eikä pyörää tarvitse keksiä uudestaan.

4. Mittaa, opi palautteesta ja iteroi

Sitä saat, mitä mittaat. Rajapinnan käytön mittaaminen on palautetta, josta rajapinnan tarjoajan kannattaa oppia jatkuvasti. Palaute mahdollistaa iteraation, jolla tarkoitetaan rajapinnan jatkuvaa kehittämistä pienin ja helposti hallittavin askelin. Muista kuitenkin rajapinnan versiointi tarvitaessa.

Rajapinnan kehityksessä kannattaa pyrkiä jatkuvaan yhteistyöhön sen asiakkaiden kanssa.

Vain siten tiedät, mitä tarvitaan, etkä tee turhaa työtä. Mieti myös ulkoisten rajapinnan toimintaa testaavien työkalujen hyödyntämistä, joiden avulla ymmärrät muiden käyttäjäkokemusta paremmin.

Rajapinnan käytön mittaaminen on tärkeä osa sen suunnittelua. Käytännössä voit seuraata mitä rajapintaa käytetetään (esimerkiksi IP-osoite, API-avain, käyttäjän tunnistus) ja koska (päivämäärä, kellonaika) ja mitä tietoa rajapinnan kautta käytetään ja millä tavoin.

5. Tee yhteistyötä muiden kanssa

Monella taholla voi olla samankaltaisia rajapintatarpeita. Selvitä yhteistyön mahdollisuus. Esimerkiksi 6Aika-kaupungit (Helsinki, Espoo, Vantaa, Tampere, Turku ja Oulu) ovat suunnitelleet rajapintoja yhdessä sen sijaan, että jokainen niistä tekisi työn itsenäisesti. Tekemällä yhteistyötä avoimesti myös kehittäjäyhteisön kanssa saadaan parempi lopputulos.

Rajapinnan takana oleva informaatio on harvoin täydellistä. Nopein tapa parantaa sen laatua on yhteisön antama palaute. Yhteisöt voivat auttaa myös luomalla koodiesimerkkejä, jotka puolestaan helpottavat rajapinnan käyttöönottoa. Hyvien rajapintojen ympärille muodostuu elävä ja monipuolinen, kaikkia hyödyttävä ja auttava ekosysteemi.

6. Toteuta johdonmukaisesti

Rajapinnat tehdään johdonmukaisesti toteuttajasta ja toteutustavasta riippumatta. Niissä käytetään samoja suunnittelumalleja, mutta niihin jätetään myös liikkumatilaa. Kaiken kattava standardointi on mahdottomuus. Perusteelliset monen sadan sivun vaatimusmäärittelyt ovat yleensä jo vanhentuneita valmistuessaan. Kannattaa pyrkiä siihen, että rajapinnat toimivat yhdenmukaisesti. Julkisen sektorin avointen rajapintojen sisältö tulee tarjota yhden lisenssin alla. Myös rajapinnan käyttöehdoissa pyritään yhdenmukaisuuteen. Käytä kansainvälisiä standardeja aina kun mahdollista. Standardit auttavat harmonisoinnissa ja helpottavat hyödyntämistä.

7. Tee tarkoituksenmukaisia rajapintoja

Hyvä rajapinta vastaa tiettyyn tarpeeseen. Rajapinnalla tulee olla julkisesti suunniteltu ja julkaistu elinkaari. Rajapinta suunnitellaan, toteutetaan, hyödynnetään ja lopulta poistetaan käytöstä. Rajapinta on osa tämän päivän käyttöliittymäsuunnittelua, jossa huomioidaan myös sovellukset ihmisten rinnalla. Rakenna tarkkaan rajattuja, käytännöllisiä ja helposti käyttöönotettavia rajapintoja. Yksi hyvä mittari rajapinnan laadulle on se, kuinka nopeasti ja helposti sen pystyy ottamaan käyttöön.

Julkaise rajapinnan dokumentaatiossa sen suunniteltu elinkaari (tulevaisuuden päivitykset, versiot jne.) ja päivitä suunnitelmaa säännöllisesti.

Kontribuoijat

API-manifestin tuottamiseen on osallistunut useat niin julkiselta kuin yksityiseltäkin sektorilta.

Jarkko Moilanen
Opetus- ja kulttuuriministeriö, API:Suomi -yhteisön perustaja & APItalisti

Mika Honkanen
Open Knowledge Finland, Open API työryhmän vetäjä & APItalisti

Jukka Aaltonen
IT-specialist

Ville Peltola
Teknologiateollisuus

Aapo Rista
Forum Virium Helsinki, 6Aika-rajapinnat

Annukka Varteva
Forum Virium Helsinki, 6Aika-rajapinnat

Matti Kinnunen
Codento Oy ja Open Knowledge Finland, järjestelmäarkkitehti

Teemu Ropponen
Open Knowledge Finland

Jani Karhunen
Orchid Bits, järjestelmäarkkitehti ja web-kehittäjä

Mikko Kolehmainen
Gofore Oy

Antti Poikola
Open Knowledge Finland

Eero Konttaniemi
Väestörekisterikeskus, Kansallinen palveluväylä

Kimmo Mäkinen
Valtiovarainministeriö, JulkICT

Arvi Leino
Turun kaupunki, 6Aika Avoin data

Janne Viskari
Väestörekisterikeskus

Samuel Rinnetmäki
Open Knowledge Finland

Tuula Pääkkönen

Karri Niemelä
BeAn Solutions

Yhteystiedot

API-manifestin kirjoittamiseen on osallistunut monia ihmisiä niin julkiselta kuin yksityiseltäkin sektorilta. Liity sinäkin mukaan kontribuoimalla muutosehdotuksen Githubissa. Voit myös liittyä mukaan keskusteluun API:Suomi Facebook -ryhmässä.