X-Road kehitysyhteisön tulevaisuus

Virallinen näkemys suunnasta mihin X-Road / palveluväylän kehitystä viedään on alla. Tuoreen uutisen (10.3.2016) asiasta voi lukea täältä.

Muuten hyvä mutta miksi tuolla on tuo ”Open community”? Sillä ei ole mitään kiinnekohtaa minnekään? Se lienee vain piirretty kuvaan mukaan, joka on jo sinällään hyvä asia. Sen sijaan sille avoimelle yhteisölle pitäisi tuossa kuvassakin saada joku paikka ja tehtävä.

Bottom up

Oma näkemykseni miten asiat voisi esittää ja miten yhteisölle tulee ”paikka”. Tuota virallista suuntaa edistävien kannattaisi tutustua aikaisempiin isoihin avoimen lähdekoodin projekteihin. Yksi sellainen on vaikka MeeGo. Ei koskaan onnistunut monestakaan syystä, mutta tässä on sama asetelma: kaksi isoa ja yhteisö. MeeGon tarina kannattaa selvitellä ettei mene siinä tehtyihin miinoihin. Merkit on samat.

Open community on jo alussa. Sitä kutsutaan nimellä ”Joint X-Road community” ja sen on perustanut (ja ”siunannut” muun muassa Viron keskeiset tahot) Viron ja Suomen edustajat yhteisöstä ja virallisista tahoista. Yhteisön tekemiseen voi tutustua osoitteessa: https://jointxroad.github.io.

Birth of Joint X-Road Community

Today we had a meeting with Estonian cooperation partners from RIA in the context of Ministry of Education and Culture driven project (funded also by Ministry of Finance). The project aims (among other things) to define practical community driven open source cooperation model between the countries (Estonia and Finland). During the project integration patterns with code examples are created to ease X-Road onboarding for all. All results are open source (MIT or equivalent) or open data (documents).

During the process we have come to situation where creating joint X-Road developer community between the countries makes sense and it was considered as a natural step to take. This is a historical day.

Road to joint community

It has been a long road to this point. Long story short. Deeper community style open X-Road related cooperation between Estonia and Finland was initiated in the context of EduCloud development around June 2014. Without Andres Kütt’s contact and invitation to have lunch in Helsinki to discuss X-Road REST support, we probably would not be here – creating joint developer community. That was one of the turning points. After that we initiated development of REST gateway support to X-Road, in which Petteri Kivimäki from Population Register Centre took the lead and did most of the work.

Ever since we have had practical workshops in small circle and online meetings now and then, when ever needed. Now it’s time to take the next step. All code created so far have been in Github all the time open for participation and review. As experienced developers know, having code in Github does not equal community nor actual open source development. It’s just code.

Decision to initiate open X-Road developer community

Today we decided to establish joint Slack for the developer community as well as shared Github organization. In the meeting we had participants from both sides: Andres Kütt (RIA, Architect), Heiko Vainsalu (RIA, X-Road Area Manager), Petteri Kivimäki (Systems manager, Population Register Centre), Jarkko Moilanen (Senior Advisor, Ministry of Education and Culture), Taija Björklund(Project coordinator, Sampo Software Oy).

This does not however mean that all X-Road code is added under Joint X-Road Community. Core components are still managed by Population Register Centre. What will be in the community Github in the first phase are:

• X-Road Integration patterns. Documents will be elsewhere too and writing process takes place in coauthoring platform overleaf.com, which has github connection)
• Code examples for basic operations in X-Road including communication with Security Server
• Code examples related to integration patterns

Primary technology for which the code examples are created, will be defined soon. One of the strong candidates is java since X-Road is also java based. Several other programming languages and platforms were discussed: PHP, Python, Ruby, NodeJS. Heiko Vainsalu will create a ”questionare” to the Estonian X-Road community about minimal set  of technologies to find out what they consider most important. Integration patterns and code examples are beginning of process which aims at creating so called developer package or SDK for X-Road. Developer package should possibly include API standards (adopted from UK most likely), X-Road interface description and sample messages. Github organization will be created and populated soon.

This is your chance to participate in creating developer package for X-Road.

Join the community Slack from https://joinxroadcommunity.herokuapp.com/

Since we have Estonians and Finnish participants, the common language is English. Slack includes private discussions, which might be the channel for native language discussions.

Community is not the place for trolling or official X-Road technical support channel. It focuses on the items mentioned above.

Over time community should become the primary place for all X-Road technical discussions.

Behave nicely and be active. We keep Slack open for all, but if issues occur, we might need to take actions. Normal debates are of course allowed but any kind of abusive language is prohibited. You know the drill, behave as in any other viable open source communities. If you have issues in the community, first person to contact is community manager.

Community manager and events

To get things rolling, we are hiring Community Manager to initiate community portal, activate developers, help in growing the community and to act as community voice towards officials such as Population Register Centre. Community manager will start during this month. We are planning to have developer community events already this year. One of the events will be about creating code examples for the integration patterns. What we also discussed was merging of Estonian and Finnish community events. Estonia ha been organizing community events for some time. It does not make sense to have two similar events on the both sides of gulf.

Expand to global X-Road community

Community building merges now Finnish and Estonian community members. I don’t see any reason why we should stop there. Consider this as open invitation for all local X-Road developer communities around the world to join.

It’s free and open. Join the community https://joinxroadcommunity.herokuapp.com/

Tarvitaan KaPA evankelistatiimi

Jäin miettimään evankelisointia hieman enemmän sen jälkeen kun VRK:n Viskari ”virallisti” X-Road -evankelista roolini. Tarkennetaan nyt vielä, että sinänsä mikään ei heti ainakaan omalla kohdalla muutu. Minua ei siis palkattu tai siirretty VRK:n alle.  Jatkan OKM:ssä entisten toimieni parissa kehittämispäällikkönä, jotka kyllä liippaavat vahvasti palveluväylää ja kansallista arkkitehtuuria. Pidän virastani ja sen sisällöstä 🙂 sainhan rakentaa sen aikalailla oman makuni mukaan.

Kansallinen palveluarkkitehtuuri (KaPA) tarvitsee evankelisteja, henkilöitä joilla on palava halu saada teknologia käyttöön laajasti.

Evankelismi on markkinointia, mutta se ei ole ”vain” markkinointia. Evankelistat tulisi olla jo ennen kuin ollaan ns valmiita tuotteen tai palvelun kanssa. Evankelista on se joka ensiksi kokeilee tuotetta tai palvelua ja alkaa rakentamaan sen toimivien osien ympärille yhteisöä yhdessä yhteisömanagerin kanssa.

Yhteisö on nykyään osa tuotetta, ei jotain mikä tehdään erikseen tai voidaan jättää pois.

Evankelisointi on monesti laitettu ja uskottu yksille harteille. Se olisi virhe ainakin KaPA:n kohdalla. Yksi henkilö pelkästään ei riitä. Riho Oks joka vei X-Tee / X-Roadin Virossa läpi, ei tehnyt kaikkea yksin. Hän oli enemmän evankelistatiimin vetäjä vaikka tekikin paljon työtä myös ns ”kentällä”. Riho Oks vei nimenomaan X-Tee / X-Road konseptia eteenpäin. X-Road ei ole sama asia kuin kansallinen palveluarkkitehtuuri.

Palveluväylä on tiedon turvallinen valtaväylä. Palveluväylä on:

• tiedonvälityskerros, joka määrittää, miten tietoja ja palveluja välitetään eri tietojärjestelmien välillä
• tiedonvälityspalvelu, jonka avulla julkinen hallinto ja yritykset voivat hyödyntää muita väylään liittyneitä palveluita ja tietovarantoja.

Palveluväylä toteutetaan teknisesti Virossa käytössä olevan X-roadin (tiedonvälitysalustan) pohjalta ja samoilla periaatteilla.

Palveluväylä on muutakin kuin tekniikkaa, sillä sen tarkoituksena on:

• mahdollistaa palvelujen ja tietovarantojen yhtenäinen kokonaisuus
• mahdollistaa standardoitu, turvallinen ja hallittu ympäristö
• madaltaa tiedonvaihdon kynnyksiä
• mahdollistaa uudenlaisia toiminta- ja toteutusmalleja.

Aika on kypsä evankelistoille

Palveluväylä on yksi digitalisaation kulmakivi. Palveluväylä on menossa tuotantokäyttöön marraskuussa. On siis aika alkaa viimeistään nyt voimakkaammin viestimään palveluväylästä ja ”myymään” sen ympärillä olevia mahdollisuuksia. Tunnistusratkaisut (vahvoihin menetelmiin perustuva ja ns heikkoja tunnistusmenetelmiä tukeva ratkaisu) lähestyvät tuotantokypsyyttä. Ensimmäiset palvelunäkymät pullautetaan piakkoin ulos.

Olisi siis aika alkaa miettimään nykyaikaista markkinoinnin ja käyttöönoton/jalkautuksen tiimiä. Osia tällaisesta tiimistä on ainakin suunniteltu palveluväylän puitteissa. Uskon, että samaa on harrastettu KaPA:nkin puitteissa mutta ulos ei välttämättä ole asiasta viestitty. KaPA on parantanut viestintäänsä huimasti verrattuna siihen mitä se oli 2014 alussa. Silti löytyy paljon petrattavaa. Tehokas ja ketterä evankelista toiminta olisi se tarvittava nykäys eteenpäin.

Evankelistat sytyttävät tulen ja yhteisömanagerit pitävät sen palamassa

Ei, nyt en viitannut palaviin alustoihin, jotka tulivat hyvin tutuksi Suomessa joitakin vuosia sitten. Siinä mielessä ehkä tosi epäonnistunut analogia ja olisi ehkä pitänyt jättää pois 🙂

KaPA tarvitsee tiimin, jossa tulisi olla ehkäpä seuraavilla fokuksilla toimivat evankelistat.

• Johtava evankelista (kapellimestari ja katsoo evankelitoimintaa ison kuvan kannalta)
• Kehitysyhteisön evankelista (rakentaa eSuomi Service Development Kit pakettia ja toimii siltana ”kehittäjien ja tuotteiden välillä”)
• Tukevien palveluiden evankelista (tunnistus, roolienhallinta, perustietovarannot, yms)
• API -evankelista (API:t keskeinen elementti KaPA:ssa ja siksi tulee olla erillinen rajapintojen käytön ja yhtenäistämisen edistäjä)
• Asiakas -evankelista (asiakastuen ja myynnin fokus)

Evankelistat ja yhteisömanagerit (palveluväylä kontekstissa tulee olemaan ainakin yksi) toimivat yhteistyössä.  Heidän vastuullaan olisi myös suunnitella hackathonien ja muiden tapahtumien aikataulutus ja skoupit.

Miten yllä mainitut evankelistat eroavat toisistaan? Rooleja ja tehtäviä voi hahmotella Venn diagrammia käyttämällä ja laittaa siihen tyypilliset liiketoiminnan ulottuvuudet. Kaikkia ei tarvitse nimittää tai palkata aluksi. Tilannesilmää käyttäen päävastuun kantava evankelista kasvattaa oman iskunyrkkinsä resurssien antamissa puitteissa. Alla on muutaman evankelistan fokusta hahmoteltu. Detaljit saa rakentaa ja päättää sitten se palkattu täysipäiväisesti tätä osa-aluetta orkestroiva evankelista. Olen ihan varma että evankelistat ovat jo organisaatiokaaviossa; ei ehkä samoilla tässä käytetyillä nimillä mutta kuitenkin.

X-Road evankelistaksi

Kesästä 2014 olen ollut omatoiminen palveluväylä/ X-Road / kansallinen palveluarkkitehtuuri yms evankelista. Homma lähti siitä, että minulta alettiin kysellä erilaisissa palavereissa, kekkereissä ja tilaisuuksissa X-Roadiin liittyvää, pääasiassa varmaan siksi että olin virolaisten kanssa paljon tekemisissä EduCloudin puitteissa. Siinähän on myös ajatuksena hyödyntää kansallista arkkitehtuuria ja EduCloudin kyljessä on tehty alaikäisten tarpeet huomioivaa SSO ratkaisua (yhteensopiva kansallisen arkkitehtuurin kanssa).

Toimintaa ja osallistumista

Sittemmin aloin olemaan aktiivisempi ja toin palveluväylään liittyviä mahdollisuuksia enemmän esiin eri yhteyksissä. Aiemmin olin mukana REST tuen rakentamisessa. Osana yhtä isompaa VM:n rahoittamaa projektia aletaan nyt rakentaa pohjaa X-Road kehittäjäyhteisölle, ei mitään massiivista budjettia mutta saadaan ainakin yhteisömanageri ja vielä jää resurssia muuhunkin. Viimeisin kontribuutioni on Suomen yhteisön kuulumisten kertominen Virossa pidetyssä X-Road community tapaamisessa (kuva alla). Iso osa evankelistan työtä onkin kiertää tapahtumia ja lisätä tietoisuttta.

Siellä puhuin asiaani ilmeisen vakuuttavasti ja suurella tunteella, koska minua verrattiin Riho Oksiin, joka on siis henkilö jonka ansiosta X-Road on se mikä se on ja käytössä Virossa.

Osa virkatyötä

Nykyisessä virassa ja vastuualueella joka minulle kuuluu (koulutuspolitiikka ja pilvipalvelut) on vaikea olla olematta jatkuvassa kosketuksessa palveluväylään ja muihin kansallisen palveluarkkitehtuurin komponentteihin. Henkilökohtainen palava innostus API:en suunnitteluun, hallintaan ja kehittämiseen liittyen ei ole ainakaan pahitteeksi. Viimeisin alkuunlaittamani konsepti #digipalvelutehdas tehtävä on nopeuttaa uusien kansalaisten arkea helpottavien kansallista palveluarkkitehtuuria hyödyntävien digitaalisten palveluiden kehittämistä.

Suomen ensimmäinen X-Road evankelista

27.8.2015 asti on siis menty periaatteella: mitään ei kysellä ja tehdään. No ei kysellä juuri jatkossakaan, mutta nyt on mandaatti toimia X-Road evankelistana Suomessa. Tämä pitänee tulkita niin että olen Suomen ensimmäinen X-Road evankelista.

A technology evangelist is a person who builds a critical mass of support for a given technology, and then establishes it as a technical standard in a market that is subject to network effects. An evangelist promotes the use of a particular product or technology through talks, articles, blogging, user demonstrations, recorded demonstrations, or the creation of sample projects. The word evangelism is taken from the context of religious evangelism due to the similarity of relaying information about a particular set of beliefs with the intention of converting the recipient.

Liity mukaan

Mielelläni näkisin, että löytyisi muitakin. Pitää vielä Viskarin ja muiden kanssa neuvotella, että miten homma hoidetaan win-win ratkaisulla. Joka tapauksessa, olen mielelläni rakentamassa palveluväylä evankelista iskunyrkin. Oma fokukseni ja vahvuuteni on kehittäjänäkökulman huomioimisessa osana palveluväylää ja kehittäjäyhteisön kehittämisessä ja rajapintoihin liittyvissä asioissa prosesseista bisnekseen. Toiset evankelistat ovat sitten fokusoituneet kenties toisiin asioihin. Ota yhteyttä vaikka Twitterissä: @kyyberi

Aims for the X-Road community

Heiko Vainsalu (X-Road Area Manager) invited me to speak at the Estonian X-Road Community event 26.-27.8.2015 about the Finnish X-Road Community, it’s past, present and future activities. It’s a joint presentation together with Petteri Kivimäki (VRK). First I was like, what do I have to say about this? X-Road is Ministry of Finance driven effort?

In a flash I remembered that my community touch and blogging about REST support were probably the reasons to be invited. I will make my presentation community focused and the second slide is below

Officially the aims regarding X-Road in Finland is to have 40 (now 5) production level services in the system during 2016. Currently there is around 20 connected services in X-Road development environment. My approach is a bit different. I’m not saying that it’s better; it’s just diferent. I choose the customer focus approach. To make it clear, developer is customer as well.

10->100->1000

The above screenshot defines the targets for community development. First of all, we need to have factory like process to evaluate new service ideas which should come from citizens. The amount of ideas in ideal situation at the end of year 2016 would be 10 each month. This is where Digipalvelutehdas (eService Factory) steps in. It provides process and services to collect new services ideas, user stories and build first mockup fast. I will present the basic idea and functions of Digipalvelutehdas in the event.

To forge ideas into services, we need organizations, both public and private. Public sector’s role would be funding, providing national service infrastructure to utilize and provide access to some crucial data storages. Private sector will provide efficient service design and development tools, methods and personnel. Given amount 100 is just nice round figure and fits into the pattern. That amount is not hard to gain, we probably have that already depending on the criteria.

That kind of engine is build on top of active citizenship; citizens are involved, provide service ideas, vote on other’s ideas, provide user stories and evaluate results. This has to be mass and getting 1000 citizens involved in developing X-Road and services on top of it, requires community management. Those familiar with community management know that getting people involved is often easy, keeping the involved is harder. One way to compensate fading citizens is to use what I call ”Russian tactic”, recruite more and more people and push them forward.

All that should be created jointly with Estonia and Finland. We both will use X-Road as foundation for digital services. Why not share the knowledge among developers as well?

Digipalvelutehdas palveluväylässä – kynnystä alaspäin

Digipalvelutehtaan tarkoitus:

• vauhdittaa digitaalisten palveluiden kehitystä osaksi kansallista palveluarkkitehtuuria.
• madaltaa kehittäjien, yritysten ja muiden kiinnostuneiden kynnystä alkaa hyödyntämään palveluväylää.
• lyhentää digitaalisten palveluiden kehityskaarta tarjoamalla kehikko ja välineet kansalaisten tarpeista syntyneiden palveluideoiden nopeaan testaamiseen.

Lähinnä näistä syistä Digipalvelutehdas on liittynyt palveluväylän kehitysympäristöön ja pystyttää oman liityntäpalvelimen (viitearkkitehtuurin nimitys) / turvapalvelin (X-Road nimitys) yhteisön käyttöön. Palveluväylän kehitysympäristöön liittyviin faktoihin voi perehtyä osoitteessa palveluvayla.fi

Liityntäpalvelimen asentaminen on sinänsä taito ja sekin on osattava. Se on kuitenkin aika triviaalia eikä niin mielenkiintoista. Sen sijaan kiinnostavampaa on mitä liityntäpalvelimen kautta voi tehdä ja miten se toimii käytännössä. Tästä syystä pystytämme liityntäpalvelimen valmiiksi, jotta voimme yhteisönä oppia miten palveluväylää hyödynnetään ja kehitetään.

Miksi se minua kiinnostaisi? Liityntäpalvelimen käyttö on syytä opetella, koska se on juuri se väline, jonka kautta omat palvelut lisätään väylään muiden käytettäväksi. Lienee fiksua järjestää muutamia liityntäpalvelimen käyttöön keskittyviä hackthon/meetup tyyppisiä tapahtumia pika puolin kenties yhteistyössä VRK:n kanssa. Kehitysympäristö on luultavasti (oma mihinkään faktoihin perustumaton arvaus) myös se paikka missä erilaiset rajapinnat ja palvelut tulevat ensin käyttöön ja siten pääsee etukenossa tekemään testiä. Ympäristö on nimensä mukaisesti testaamista varten eikä mitään palvelulupausta sisälly sen käyttöön.

Luonnollisesti tahot, jotka ovat mukana Digipalvelutehtaan toiminnassa voivat tulla mukaan käyttämään yhteistä liityntäpalvelinta. Digipalvelutehdas on kuitenkin avoin yhteisö, joten ei muuta kuin mukaan vaan. Lisätietoja: jarkko . moilanen (at) minedu . fi ja digipalvelutehdas.fi

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)