Ajatuksia palveluväylän liityntäkatalogista

Tapaaminen Viskarin ja Kopposen kanssa pisti harmaat aivosolut liikkeelle mystisen liityntäkatalogin suhteen. Sen olisi tarkoitus olla kehittäjien suuntaan luotu ”honey pot” palveluarkkitehtuurin API:en suhteen. Nimi pitää kyllä mennä uusiksi… jotain hieman kehittäjähenkistä. Noh, olin jo jonkin aikaa tätä kansallisen palveluarkkitehtuurin API -hallintaan liittyvää asiaa tuumaillut hiljaa (joskus) itsekseni, mutta koskaan en ollut yhdistänyt että liityntäkatalogi olisi ”se” juttu. API:t siis ovat intohimoni, jos lukija ei vielä sitä tiedä. API:suomi yhteisö on yksi intohimon ilmentymiä. No, mutta siis liityntäkatalogi. CSC:n selvityksessä liityntäkatalogia on kuvattu seuraavasti:

Sähköisten palveluiden toimintaperiaatteita ja rajapintoja kuvaileva luettelo. Liityntäkatalogin tarkoituksena on auttaa palvelun tuottajia ja toteuttajia kehittämään tehokkaampia sähköisiä palveluita ja tukemaan tietojen uudelleenkäyttöä. Liityntäkatalogiin kuvataan sähköiset palvelut, joissa käsiteltävät tiedot ovat muiden tietojärjestelmien hyödynnettävissä. 

Eikös X-Road tarjoa katalogin?

Joku voisi kysyä että eikös se X-Road jo tarjoa jonkinlaisen katalogin? Eikös se ole yhtä kuin tuo? No ei oikein. Pelkät rajapintojen kuvaukset eivät vielä tuota kyseistä palvelua. Lisäksi on paljon rajapintoja jotka eivät ole palveluväylän päällä. Ei palveluväylästä ole tarkoitus  tehdä uutta internettiä. Tulee siis ainakin harkita jotain kokoavaa palvelua.

Yllä olevaa kuvausta voisi pitää myös alustavana palveluvisiona tai tuotekuvauksena. Sieltä paistaa läpi kehittäjä. Liityntäkatalogi tulee siis tehdä kehittäjän näkökulmasta. Se eroaa selkeästi palvelujen kuluttajan näkökulmasta, jonka tarpeisiin paremmin sopii puolestaan palvelukatalogi: ”Palveluita kuvaileva luettelo tai portaali, jonka tarkoituksena on parantaa palveluiden löydettävyyttä. Palvelukatalogeina voidaan pitää esimerkiksi suomi.fi tai gov.uk -portaaleja.” Mutta siis kehittäjän näkökulmasta ja ottaen huomioon että rajapinnat eli API:t ovat keskeisessä roolissa, tulee palvelua miettiä APX eli API eXperience ja DX eli Developer eXperience näkökulmista. APX on API:n käyttökokemus jonka voidaan nähdä ottavan huomioon seuraavat näkökulmat:

•  API on tarkoituksenmukainen lisäarvoa tuottava palvelu
• yksinkertainen käyttää ja omaksua
• tehokas
• hallinnoitu ja mitattavissa
• ajantasainen dokumentaatio
• automatisoitu kehittäjätuki (SDK:t)
• itsepalvelu tyyppinen asiointi

Tuosta listasta voi nähdä että APX on pääasiassa rajapintojen tuottajien murhe, mutta tässä tapauksessa kannattaa tehdä liityntäkatalogin kehittäjätahon kanssa yhteistyötä. Siitä hetken päästä lisää.

Liityntäkatalogin tehtävistä ja palveluista

SDK:t, esimerkkikoodien, dokumentaation ja hiekkalaatikoiden generointi voidaan tehdä myös liityntäkatalogin päässä. Näin se tulisikin itse asiassa olla. Tämä takaisi yhdenmukaiset dokumentaatiot ja välineet API:en kuluttajien näkökulmasta ja tiputtaisi oppimiskulmaa huomattavasti. API omistajan ei siis kannata tehdä itse kaikkea työtä, koska edellä mainitut generoinnit voidaan automatisoida.Monet REST /JSON API:t on dokumentoitu Swaggerin 1.0 formaatilla ja se perustuu dokumentaation generoimiseen koodin seassa olevista kommenteista. Liityntäkatalogin tulee tukea tätäkin tapaa tuoda dokumentaatio, koska siten saadaan ”legacy” REST/JSON API:t mukaan. Onpas outoa käyttää legacy sanaa REST/JSON yhteydessä. Tottunut että ne legacyt on SOAP rajapintoja.

Design first

Automatisointi puolestaan edellyttää sitä että API omistaja eli sen kehityksestä vastaava taho ottaa käyttöön design first- lähestymistavan. Lyhyesti sanottuna tarkoittaa sitä että rajapinta suunnitellaan ensin tarkoituksen mukaisella kuvauskielellä kuten RAML tai API Blueprint (ja swagger 2.0) ennen kuin tehdään yhtään mitään muuta. Suunnittelu tehdään yhdessä API:n hyödyntäjien kanssa. Syntyneestä kuvauksesta voidaan generoida muun muassa API:n runko (joka sitten täydennetään toimivaksi), SDK:t ja dokumentaatiot. Näin ollen API:n tuottajan kannattaa tehdä API kuvaus ja edellyttää liityntäpalvelulta kykyä hyödyntää kuvausta. Tätä prosessia käsittelee toinen kirjoitukseni, ja kuvauskielien vertailusta toinen.

Tässä vaiheessa lienee hyvä esittää asiaa kuvana.

Kuvassa siniset objektit ovat enemmän tai vähemmän API:n tuottajiin liittyviä. He tuovat esim RAML kuvauksen API-hallintaan, joka sitten käyttää RAML kuvausta pohjana ja generoi SDK:t, dokumentaatiot yms. RAML tuonti voi tapahtua API:n kautta tai sitten manuaalisesti, kumpikin tapa pitää mahdollistaa. Näin siis ainakin ns avointen API:en kohdalla. Toinen API:en metatietovirta tulee palveluväylästä (X-Road). Todennäköisesti tähän väliin, X-Road hallinta ja liityntäkatalogi tulee filtteri joka määrittää mitkä API:t viedään katalogiin. Nämä API:t voivat olla sellaisia jotka eivät ole täysin avoimesti käytössä.

Analogiana voisi käyttää normaalia API:n kehitystä, jossa aloitetaan normaalisti 1) omalla sisäiseen käyttöön tarkoitetulla rajapinnalla, sitten laajennetaan API:n käyttöä 2) kumppaneihin ja lopulta avataan 3)  avoin API. Jotain tämän tyyppistä API julkisuusluokittelua tulisi harkita. Joka tapauksessa, nyt tulee API:en metatiedot yhteen pisteeseen.

Katalogi jota kehittäjä käyttää

Todennäköisesti API:n omistaja joutuu jonkin verran tekemään manuaalista työtä viedessään API:a ensimmäistä kertaa hallinnan piiriin.

API:lle muodostuu profiiili, jossa on kaikki olennainen metatieto asiakkaan eli kehittäjän ja hallintajärjestelmän kannalta katsoen. 

Joka tapauksessa näistä tiedoista muodostuu tietovaranto, jonka päälle voidaan rakentaa itse katalogi. Tällä katalogilla on erittäin suuri merkitys API:n löydettävyyden kannalta. API josta kukaan ei tiedä tuskin saa paljon käyttöä.

Punaisella värillä on ilmaistu kehittäjään liittyviä asioita ja toimia. Hän luonnollisesti käyttää katalogia löytääkseen rajapinnat mitä käyttää, opettelee niiden käyttöä tarjottujen dokumentaatioiden ja ”hiekkalaatikoiden” avulla. Sen jälkeen varmaan lisää rajapinnan sovellukseen. Sovellukselle syntyy profiili, jossa kerrotaan sovelluksesta tai palvelusta olennainen tieto jälleen kerran liityntäpalvelun näkökulmasta ja toisten kehittäjien näkökulmasta. Miksi? No siksi että kyseisiä profiileja käytetään use case esimerkkeinä ja ne listataan API:en viereen. Näin kehittäjällä on joku mistä katsoa miten API oikeasti on käytössä. Varsinaisiin rajapintoihin kehittäjän palvelu pääsee API -hallinnan läpi käyttäen esim API -avainta. Myös avoimet API:t kannattaa laittaa API-hallinnan piiriin, jotta on joku tieto mihin ja kuka niitä käyttää. Tarvittaessa käyttö voidaan voidaan estää, mikäli joku alkaa pommittamaan rajapintaa ilman perusteellista syytä.

EDIT: Kuvasta se ei tule ilmi, mutta oma ajatukseni olisi hajauttaa API:en hallinta sektoreittain. Näin hallintotaakka jakaantuu eikä kukaan muutenkaan olisi valmis ottamaan sitä harteilleen kansallisella tasolla. Tarvittaessa voidaan sitten harvestoida metatiedot yhteen nippuun.

Palvelukohtaiset API-avaimet

Liityntäkatalogia tehdessä kannattaa miettiä myös API -avainten käyttöä. Normaalisti API -avaimet joilla siis saa rajapinnan käyttöön on kehittäjäkohtainen. Tämän sijasta voisi olla järkevää tehdä sovellus/palvelu kohtainen API-avain, jota kyllä hallinnoi kehittäjä. Tämä lähestymistapa irrottaa yksittäisen kehittäjän palvelun käyttämistä API-avaimista. API-avaimet voisivat olla ”organisaation omaisuutta”. No, tämä vain ajatuksena.

Tässä kuvattua mallia on alettu määrittämään APIKA -palveluna ja sen toteutus tultaneen aloittamaan syksyllä Digipalvelutehtaan kehitysmallin mukaisesti. Mukaan saa tulla 🙂 Jos arveluttaa kylmiltään hypätä mukaan, niin ota yhteyttä.

Jarkko Moilanen (at minedu.fi)