API-tuotannon tasot kansallisessa palveluarkkitehtuurissa

Aiemmin tällä viikolla kansallisen palveluväylän liityntäkatalogi oli yksi aiheista, joita tuli pähkittyä enemmän tai vähemmän. Jäin miettimään mallia astetta syvemmältä ja miten kuvata eri toimintoja. Välillä tuntuu, että kertaan itsestään selviä asioita. Tarkoitus on päästä pikku hiljaa työkalutasolle pois metatason malleista kohti käytäntöä.

APIOps verkosto

Sittemmin päätin Tampereen APIOps verkoston vetäjänä, että käsittelemme yhtä katalogin ympärille kuvattua toimintamallia kaikille avoimessa 8.8.2015 pidettävässä APIOps meetupissa. APIOps verkostosta ja sisällöstä voit lukea lisää APIOps -yhteisön verkkosivuilta. APIOps on juuri sitä developer, API -kehittäjä, ylläpitäjätason asiantuntijuutta ja näiden asioiden ympärille rakentumassa oleva yhteisö. APIOps onkin avoin verkosto, joka olisi omiaan toimimaan kehittäjäyhteisön pohjana myös kansallisia rajapintaa-asioita ja ratkaisuja mietittäessä ja kehitettäessä.

Screenshot from 2015-08-02 11:16:41

Kolmen tason malli

Kolme?! No jostain sitä on aloitettava. Sunnuntain ratoksi piirtelin suoraan stetsonista tasoja, joita kansallisen tason API-tuotannosta saattaisi löytyä. Taustalla ei ole mitään tietoisesti valittua suurta tietojärjestelmän teoriaa. Matkalla tuli generoitua akronyymeja ja uusia termejä. Kannattaa siis lukea pienellä varauksella.

Malli kumpusi enemmän takaraivosta(tm) kuin tutkitusta tiedosta.

Lähempänä yläreunaa on API:en kuluttajat ja heidän tarpeensa. Mitä alemmas kuvassa mennään, sitä lähemmäs päästään API:en juuria päätyen lopulta sinne konehuoneeseen. Välissä on mielenkiintoinen kerros, jossa yhteistyö ilmenee selkeimmillään.

api-metatietoa-suppilo

API eXperience (APX)

Tämä on se taso missä:

API kohtaa palvelun kehittäjän, joka käyttää useita rajapintoja yhden palvelun tietojen hakemiseen/muuttamiseen ja tapahtumien prosessointiin.

Jotkut käyttää termiä developer experience, mikä viittaa kyllä ehkä laajempaan kokonaisuuteen, mutta eipäs se suuri virhe olisi käyttää sitäkin tässä. Se milloin APX on ehkä selkeästi perusteltu termi on tilanteet kun rajapinta on oikeasti tuote, sitä osataan ajatella tuotteena ja myydä tuotteena. Voisiko olla niin että API eXperience viittaa enemmän itse API:n käyttöön ja tuntumaan ja Developer eXperience API:n ympärille syntyneseen kokonaisuuteen. Jos näin on, niin nimi pitää vaihtaa DX:ksi. Tätä akateemiselta haiskahtavaa semantiikkaan viittaavaa jaottelua pitää pohtia sitten joskus. Mulesoftin CTO on kirjoittanut APX:stä ajatuksia herättävän blogautuksen.

Design eXperience (DSX)

Tämä on mielenkiintoinen kerros tällä hetkellä. Osa rajapinnoista on toteutettu ajatuksella: koodataan-> generoidaan dokumentaatio. Näin ainakin Swagger 1.0 ajattelu menee. Lähestymistavasta käytetään termiä bottom-up. Swagger on siirtymässä kohti ”mainstream” tapaa: design first.

Nykyaikaisempi lähestymistapa on tehdä ensin kuvaus rajapinnasta (yhdessä eri sidosryhmien kanssa), yritetään ottaa eri tarpeet huomioon ennen kuin tehdän mitään muuta. Tämä voidaan tehdä esim RAML ja API Blueprint formaattiin, mutta itse prosessi voi olla vaikka pahvikorttipohjainen.

API -kuvaus on yhteisöllinen sopimus siitä miten toteutus vastaa eri tilanteissa ja miten sitä käytetään

Kuvauksesta voidaan generoida mock-up palvelin, jolla voidaan testata miten API toimisi ja mikä sen ”tuntuma” on. Muutamia työkaluja tähän on, mutta tilaa on markkinoilla uusillekin. Kuvauksesta voidaan generoida myös varsinaisen API:n runko (skeleton) useille eri kielille. Samoin SDK:t ja dokumentaatiot syntyvät automaattisesti. Se mitä ei synny automaattisesti on esimerkit miten rajapintoja on käytetty erilaisissa palveluissa. Generointiin on jo läjä työkaluja. Joskus prosessi saattaa vaatia moniportaisen toolchain mallin, mutta hyvin paljon voidaan jo tehdä.

Lisäksi kuvauksia voidaan käyttää API:en viennissä API-hallintaan, niistä voidaan muodostaa API-katalogi. Kuvassa alaosan punaiset nuolet ovat pääsääntöisesti alaspäin. Se kuvastaa tilannetta jossa design first-ajattelu ohjaa implementaatiota. Yksi nuolista on ylöspäin, swagger, koska sen 1.0 versio ei ole desing first -ajattelun mukaista. Kuitenkin swagger 1.0:aa voidaan käyttää muutaman työkalun kautta kierrätettynä myös API-profiilin luomiseen samoin kuin RAML ja API Blueprint kuvauskieliä. Pidetään kuitenkin mielessä, että useampi vaihe tarkoittaa yleensä hävikkiä tai ongelmia. Siksi KISS. Joka tapauksessa taitaa käydä niin että osa API -profiilista pitää lisätä tai muokata käsin.

Implementation & Maintenance eXperience (IMX)

Tällä tasolla API on koodattu ja pörisee jossain pilvessä. Tälle tasolle ei syntynyt luontevaa nimeä. DevOps liikkuu tällä tasolla. Kyseessä on siis kuitenkin tuntuma siitä miten helposti ja millä työkaluilla jokin API voidaan toteuttaa; miten skaalataan, miten siirretään ympäristöstä toiseen kivuttomasti (esim JulkICT Lab:sta tuotantoympäristöön), versionhallinta yms.

Ilmaise vaatimuksesi Githubissa

githubTyötä liityntäkatalogin käyttäjätarinoiden  ja vaatimusten eteen on jo tehty hieman. Keräämme kaikki tarinat yhteen paikkaan avoimesti keskustelua varten. Käy kommentoimassa jo ilmaistuja vaatimuksia (esim ”+1” kommentti niihin mitkä näet tarpeelliseksi) tai lisää omat vaatimukset. Loppusyksystä on tarkoitus saada ensimmäinen versio liityntäkatalogista testattavaksi.

Voit myös osallistua APIOps verkoston tapaamisiin, perustaa omalle paikkakunnalle oman APIOps -ryhmän.

Mainokset

Kommentoi

Täytä tietosi alle tai klikkaa kuvaketta kirjautuaksesi sisään:

WordPress.com-logo

Olet kommentoimassa WordPress.com -tilin nimissä. Log Out /  Muuta )

Google+ photo

Olet kommentoimassa Google+ -tilin nimissä. Log Out /  Muuta )

Twitter-kuva

Olet kommentoimassa Twitter -tilin nimissä. Log Out /  Muuta )

Facebook-kuva

Olet kommentoimassa Facebook -tilin nimissä. Log Out /  Muuta )

Muodostetaan yhteyttä palveluun %s