Ville Viljamaa
API:en hallinta ja Frends-integraatioalusta
Metropolia Ammattikorkeakoulu Insinööri (AMK)
Tietotekniikka Insinöörityö 12.05.2019
Tiivistelmä
Tekijä Otsikko Sivumäärä Aika
Ville Viljamaa
API:en hallinta ja Frends-integraatioalusta 68 sivua + 3 liitettä
12.5.2019
Tutkinto insinööri (AMK)
Tutkinto-ohjelma Tietotekniikka Ammatillinen pääaine Ohjelmistotekniikka Ohjaajat
Lehtori Juha Kämäri
Insinöörityössä tutustuttiin käsitteeseen API:en hallinta ja siihen mitä, eri osa-alueita se pi- tää sisällään sekä minkälaisia API:en hallintaan tarkoitettuja ominaisuuksia Frends-integ- raatioalustasta löytyy ja kuinka näitä voisi hyödyntää yksinkertaisen web-rajapinnantoteu- tuksessa.
Työn teoriaosuudessa käytiin läpi, mitä web-rajapinnoilla yleensä tarkoitetaan ja minkälai- sia eri rajapintoja on tarjolla. Samalla käytiin läpi, mitä API:en hallinta pitää sisällään, sekä niitä API:en hallintajärjestelmien ominaisuuksia, joilla API:en hallintaa toteutetaan.
Itse työ oli yksinkertaisen web-rajapinnan toteutus Frends-integraatioalustalla, jossa tarkoi- tuksena oli yhdistellä useita palveluita yhdeksi kokonaisuudeksi yhden rajapinnan alle. Sa- malla pyrittiin hyödyntämään Frendsin tarjoamia API:en hallintaan tarkoitettuja ominaisuuk- sia.
Avainsanat API:en hallinta
Author Title
Number of Pages Date
Ville Viljamaa
API Management and Frends integration platform 68 pages + 3 appendices
12 May 2019
Degree Bachelor of Engineering
Degree Programme Information Technology Professional Major Software Engineering Instructors
Juha Kämäri, Senior Lecturer
This thesis tries to define what is API Management and what aspects are a part of it. It also focuses on what kind of API Management properties are found on Frends integration plat- form and how one might utilize them on defining and creating a simple web interface.
The theory section goes through basics of web interfaces and what kind of interfaces are available. Section also tries show different aspects of API Management and demonstrate properties that an API Management solution should have, so that API Management can be implemented properly.
In the last section of the thesis a simple web interface is created using Frends integration platform. Web interface was created so that you could join different web-services combin- ing them into a single service under one interface and at the same time demonstrate differ- ent aspects of API Management on Frends integration platform.
Keywords API Management
Sisällys
Lyhenteet
1 Johdanto 1
2 Rajapinnat ja API Management 2
2.1 API 2
2.2 Miksi API:t ovat tärkeitä? 3
2.3 Miksi API:en hallintaa tarvitaan? 3
3 API Management 4
3.1 API:en hallintomalli 5
3.2 API:en hallintajärjestelmä 7
3.2.1 API-Gateway eli API-yhdyskäytävä 7
3.2.2 Developer portal eli kehittäjäportaali 8
3.2.3 Management portal eli hallintaportaali 9
4 Frends 10
4.1 Frends arkkitehtuuri 12
4.2 Integraatioiden toteutus, käynnistys ja suoritus 14
4.3 Agentit 22
5 Yksinkertaisen rajapinna toteuttamien Frendsillä 24
5.1 Taustapalvelut 24
5.1.1 Imagecharts 25
5.1.2 WebserviceX 25
5.1.3 Dropbox 25
5.2 Suunnittelu 26
5.3 Toteutus 37
5.3.1 POST-Prosessi/päätepiste 42
5.3.2 GET- ja DELETE-prosessit/päätepisteet 60
5.4 Rajapinnan testaus 63
5.5 Yhteenveto 65
Liitteet
Liite 1. POST-prosessin toteutus BPMN-kaaviona Liite 2. GET-prosessin toteutus BPMN-kaaviona Liite 3. DELETE-prosessin toteutus BPMN-kaaviona
Lyhenteet
BPNM Business Process Model and Notation. Liiketoimintaprosessien kuvaami- seen tarkoitettu kieli.
API Application Programming Interface. Ohjelmointirajapinta
SOAP Simple Object Access Protocol. Tietoliikenneprotokolla, jonka pääasialli- sena tehtävänä on mahdollistaa etäproseduurikutsut.
RPC Remote Procedure Call. Etämetodikutsu, jolla voidaan kohdeympäristössä käynnistää jokin tapahtuma.
CRM Customer-relationship management. Asiakkuuksien hallintaan tarkoitettu järjestelmä.
REST Representational state transfer. http-protokollaan perustuva arkkitehtuuri- malli ohjelmointirajapintojen toteutukseen.
JSON JavaScript Object Notation. Avoin tiedostoformaatti, jonka tarkoituksena on välittää tietoa ihmisen luettavassa muodossa.
XML Extensible Markup Language. Merkintäkieli, jota käytetään tiedonvälityk- seen.
DLL Dynamic Link Library. Windows-käyttöjärjestelmällä käännetty jaettu kir- jasto.
YAML YAML Ain’t Markup Language. Merkintäkieli, jota käytetään muun muassa rajapintakuvausten toteuttamiseen.
eiPaaS Enterprise Integration Platform as a Service. Palvelu tarjoaa asiakkaalle pilvialustan, jonka päällä asiakaan on mahdollista kehittää omia palveluita.
käyttäjien tunnistamiseen ja valtuuttamiseen liittyvien tietojen jakamiseen verkossa.
GUID Globally Unique Identifier. 128-bittinen numero, jota voidaan käyttää tiedon identifioimiseen tietojärjestelmissä.
SLA Service-level agreement. Sopimus palvelun tarjoajan ja palvelun hyödyn- täjän välillä. Sisältää erilaisia saatavuusvaatimuksia, laatuvaatimuksia ja vastuumäärittelyjä.
LINQ Language Integrated Query. .NET-komponentti, joka mahdollistaa dataky- selyt.
PNG Portable Network Graphics. Rasterikuville tarkoitettu tiedostoformaatti.
DDoS Distributed Denial of Service attack. Hajautettu palvelunestohyökkäys.
1
1 Johdanto
Opinnäytetyön tarkoituksena on perehtyä käsitteeseen API:en hallinta ja tutkia, minkä- laisista osista se koostuu. Työssä käydään läpi API:en hallintaan liittyviä eri osa-alueita ja lopuksi toteutetaan yksinkertainen Web-rajapinta hyödyntäen Frends-integraatioalus- taa ja sen sisältäviä API:en hallintaa tarkoitettuja ominaisuuksia.
Rajapinnan toteutuksessa on pyritty hyödyntämään mahdollisimman montaa API:en hal- lintaan liittyvää toimintoa ja menetelmää niiltä, osin kuin se on ollut mahdollista. Koska Frends on integraatioalusta eikä puhtaasti API:en hallintaan tarkoitettu järjestelmä, suora vertailu ei ole mahdollista.
Työ on jaettu neljään osaan, joista ensimmäisessä osassa käydään läpi yleisesti web- rajapintojen käsitettä ja sitä, minkälaisia ongelmia rajapintojen määrän kasvu on aiheut- tanut. Samalla käydään läpi syitä, miksi API:en hallinnan katsotaan olevan tarpeellista ja minkälaisiin ongelmiin API:en hallinnalla haetaan ratkaisuja.
Toisessa osassa perehdytään tarkemmin API:en hallintaan ja pyritään määrittelemään, mitä API management kokonaisuudessa tarkoittaa. Työssä käydään myös läpi se, mitä eroa on API:en hallinnalla ja API:en hallintajärjestelmällä.
Kolmannessa osassa käydään läpi Frends-integraatioalustan arkkitehtuuria, miten alus- talla toteutetaan integraatioita ja kuinka integraatiot toimivat. Osassa käydään läpi myös alustan API:en hallintaan tarkoitettuja työkaluja ja ominaisuuksia.
Viimeisessä osassa toteutetaan yksinkertainen web-rajapinta, suoritetaan rajapinnan testaus ja muodostetaan yhteenveto rajapinnan toteutukseen tuloksista sekä käydään läpi mahdollisia haasteita, joita Frends-integraatioalustalla toteutetuissa rajapinnoissa saattaa esiintyä.
2 Rajapinnat ja API Management
2.1 API
API eli Application Programming Interface on software-to-software-rajapinta, eli kahden järjestelmän tai ohjelman välinen rajapinta. Rajapinta määrittelee sopimuksen, jonka avulla kaksi sovellusta voi kommunikoida keskenään ilman käyttäjän osallisuutta. (1.)
Sopimus määrittää käytettävän protokollan, minkä tyyppistä tietoa rajapinta ottaa vas- taan, kuinka sitä voi kutsua ja minkälainen vastaus rajapinnasta tulee. Ajatuksena on, että rajapinnan taustalla oleva toteutus voi muuttua, mutta rajapinta pysyy samanlaisena eivätkä muutokset näy rajapintaa hyödyntäville applikaatioille. (1.)
Koska rajapinta on etukäteen määritelty sopimus, on myös mahdollista, että esimerkiksi web-rajapinnan taustalla olevaa järjestelmää ei ole vielä olemassa tai sen toteutus on kesken. Sopimus kuitenkin mahdollistaa sen, että rajapintaa hyödyntäviä applikaatioita tai palveluita voidaan kehittää samaan aikaan rajapinnan taustajärjestelmän kanssa.
Tämä mahdollistaa nopean ja ketterän ohjelmistokehityksen. (1.)
Vaikka rajapintojen toiminta-ajatus on kauttaaltaan samanlainen, niiden hyödyntäminen riippuu rajapinnan tyypistä ja esimerkiksi REST-tyyppistä rajapintaa käytetään eri tavalla kuin vaikkapa Java API:a. Tässä insinöörityössä API:lla tarkoitetaan käytännössä web- rajapintaa, joka erään määritelmän mukaan on verkossa toimiva palvelu, jolle on määri- telty rajapinta ja sen hyödyntämiseen käytetään http-protokollaa. (2.)
Vaikka teknisesti esimerkiksi erilaiset SOAP-palvelut ja muut RPC API:t kuuluisivat myös määritelmän alle, on nämä kuitenkin rajattu insinöörityössä käsiteltävän alueen ulkopuo- lelle. Työssä on pyritty keskittymään REST-arkkitehtuuria noudattaviin rajapintoihin sekä näiden hallintaan. (3;4.)
3
2.2 Miksi API:t ovat tärkeitä?
Yritykset ja yhteisöt ovat vähitellen heränneet siihen, että heillä saattaa olla käytössään tietoa tai muita resursseja, joista voisi olla hyötyä muille yrityksille tai ohjelmistokehittäjille ja, että näiden resurssien käytöstä ollaan valmiita maksamaan rahaa.
Samaan aikaan on syntynyt yrityksiä, jotka tarjoavat palveluja, joita ei aiemmin ollut ole- massa, kuten erilaisia maksunvälitys- ja suoratoistopalveluita.
Vuonna 2014 CRM-pilvipalveluita tarjoava Salesforce.com kertoi, että 50 % heidän vuo- tuisesta liikevaihdostansa tulee API:en kautta ja esimerkiksi matkailualan verkkopalve- luita pyörittävän Expedian liikevaihdosta 90 % tulee rajapintojen kautta, joten on selvää, että rajapintojen toteuttamisesta ja niiden avaamisesta kehittäjille on hyötyä. (5.)
Rajapintojen avaaminen on myös mahdollistanut sen, että yritys voi keskittyä ydinosaa- miseen, eikä heidän tarvitse toteuttaa kaikkea talon sisällä, vaan palvelun voi ostaa ul- kopuolelta. Samalla vältytään siltä, että pyörää ei tarvitse keksiä uudestaan.
Sama palveluiden saatavuus on synnyttänyt myös uusia yrityksiä, joiden liikeidea perus- tuu suurimmaksi osaksi muiden yritysten tarjoamien rajapintojen hyödyntämiseen. Hy- vänä esimerkkinä tällaisesta yrityksestä on henkilökuljetuksia tarjoava palvelu Uber, joka hyödyntää muun muassa Twilio-viestintäalustaa ja GoogleMaps-karttapalvelua. (6.)
2.3 Miksi API:en hallintaa tarvitaan?
Rajapintojen avaaminen kuluttajien käyttöön on luonut uusia ongelmia, joihin yritysten ei välttämättä aiemmin ole tarvinnut varautua. Koska verkossa oleva rajapinta on käytän- nössä ikkuna yrityksen taustajärjestelmiin ja dataan, on selvää, että esimerkiksi verkko- hyökkäyksien mahdollisuus on ilmeinen. Samalla kun verkkohyökkäyksiin varaudutaan, pitäisi myös selvittää, kuinka varmistetaan, että rajapinnan tiedot eivät päädy vääriin
käsiin, noudattaako rajapinta yrityksen laatustandardeja, kenelle rajapinta on suunnattu, miten perutaan väärinkäyttäjiltä käyttöoikeudet rajapintaan ja niin edelleen.
API:en hallinta pyrkii vastaamaan yllä mainittuihin kysymyksiin. Vaikka usein ajatellaan, että API:en hallinta on pelkästään API:en hallintajärjestelmä, joka on asennettu fyysiselle tai virtuaaliselle palvelimelle, kuuluu käsitteen alle paljon muutakin.
API:en hallinta koostuu pohjimmiltaan kahdesta osasta, jotka toimivat yhdessä muodos- taen kokonaisuuden, jota kutsutaan API:en hallinnaksi. API Governance, eli API:en hal- lintomalli pitää sisällään rajapinnan määrittelyt ja toimintatavat, joilla rajapintaa hallitaan sekä kuinka rajapinta toteutetaan. API:en hallintajärjestelmä taas on tavallaan fyysinen toteutus edellä mainituista määrittelyistä ja sen tehtävänä on pitää huolta siitä, että mää- rittelyissä mainitut asiat toteutuvat.
3 API Management
Vaikka kentällä olevat toimijat ovat sunnilleen yhtä mieltä siitä, mitä termi API manage- ment pitää sisällään, ei termille kuitenkaan ole mitään virallista määritelmää tai standar- dia. API:en hallintajärjestelmiä toimittavat yritykset mielellään toki määrittelevät termin sen kautta, mihin heidän omat järjestelmänsä pystyvät. (7.)
Yhden melko osuvan määritelmän mukaan API:en hallinta on: geneerinen toimintatapa, jota yrityksen tulisi noudattaa huolimatta valitusta kaupallisesta hallintajärjestelmästä.
(7.)
Toisaalla taas termi on määritelty seuraavasti: Hallittu rajapinta on määritelmän mukaan hallinnan kohteena. Hallitulla API:lla on määritelty rajapinta, rajapinnalle on määritelty kohdekäyttäjäryhmä ja, rajapinta on sekä yrityksen liiketoiminnan ja IT:n hallinnassa (8.).
Molemmista lainauksista käy hyvin ilmi, että pelkästään API:en hallintajärjestelmän asentaminen tai hankkiminen ei riitä, vaan mukana täytyy olla myös suunnitelmallisuutta ja määrittelyjä, koska rajapintoihin liittyviä osapuolia on usein enemmän kuin yksi.
5
3.1 API:en hallintomalli
API:en hallintomallista on liikkeellä monenlaisia mielipiteitä, joidenkin mielestä se aiheut- taa ainoastaan ongelmia ja hidastaa rajapintojen kehitystä. Todellisuudessa kuitenkin API:en hallintomallin tarkoitus on, että tehdään etukäteen parhaat päätökset koskien yri- tyksen ja rajapinnan etua. (9;10.)
On toki mahdollista toteuttaa rajapinta ilman API:en hallintaa, mutta rajapintojen määrän kasvaessa on helppo kadottaa ote rajapinnoista ja niiden kehityksestä. On toki huomat- tava, että hallintomallin tulisi olla kevyempi kuin esimerkiksi ohjelmistoprojekteissa.
Vakka API:en hallintomalli usein sivuutetaan hankalana ja kehitystä hidastavana asiana, ulottuu sen vaikutus kuitenkin aina rajapinnan määrittelystä rajapinnan alasajoon asti.
(1.)
Brajesh De (1.) jakaa hallintomallin viiteen eri vaiheeseen:
1. API Proposal eli rajapintatarpeen esittäminen
2. Technical requirements gathering eli teknisten vaatimusten kartoitus
3. Build and validate eli toteutus ja validointi
4. General Availability eli yleinen saatavuus
5. Adoption and sunsetting eli omaksuminen ja erääntyminen.
Ensimmäisessä vaiheessa organisaation sisällä huomataan tarve uudelle rajapinnalle tai tarve toteuttaa muutoksia jo olemassa olevaan rajapintaan. Tarpeet saattavat syntyä esimerkiksi uusista sopimuksista, kaupoista tai on huomattu, että nykyinen rajapinta ei ole linjassa nykyisen bisnesstrategian kanssa. (1.)
Toisessa vaiheessa kerätään tekniset vaatimukset ja luodaan määrittelyt rajapinnalle.
Usein vaiheen toteuttajina on yrityksen bisnesanalyytikko ja API-arkkitehti, jotka luovat
yhdessä rajapinnalle määrittelyt. Samalla tulisi käydä ilmi, onko yrityksellä jo olemassa olevia sääntöjä tai standardeja, joiden mukaan toimia ja, onko näitä syytä päivittää. (1;4.)
Vaiheen jälkeen tulisi olla selkeä kuva siitä, mitä määrittelystandardia rajapinta noudat- taa, käytetäänkö rajapinnan dokumentointiin YAML:a, RAML:a vai jotain muuta doku- mentointistandardia. Samalla pohditaan, kuka on vastuussa rajapinnan määrittelyjen katselmoinnista ja hyväksymisestä, miten rajapinta versioidaan ja käytetäänkö skee- moissa myös versiointia. Edellä mainittujen asioiden lisäksi täytyy vielä selvittää, mitkä back end- järjestelmät kytketään suunniteltuun rajapintaan ja täytyykö järjestelmien vä- lillä suorittaa sanomamuunnoksia. Lisäksi tulee pohtia myös, kuinka paljon taustajärjes- telmät kestävät kuormaa, eli minkälaiseen määrään kutsuja on mahdollista vastata yh- dellä kertaa. (1.)
Kolmannessa vaiheessa aloitetaan itse rajapinnan toteutus ja tähän vaiheeseen API- hallintomallin tulisi tarjota vastauksia kysymyksiin kuten mitä työkaluja rajapinnan toteu- tukseen käytetään, mitä hyvä käytäntöjä rajapinnan toteutuksessa tulisi noudattaa, miten testaamista tulisi lähestyä. Lisäksi minkälainen on rajapinnan katselmointi ja millä tapaa varmistetaan, että toteutus vastaa laatumäärittelyjä, onko tuotanto- ja testiympäristö eriy- tetty, miten rajapinnan elinkaarta tulisi hallita ja mikä on rajapinnan elinkaaren korotus kehitysversiosta tuotantoversioksi ja lopuksi rajapinnan siirtäminen eläkkeelle. (1.)
Neljäs vaihe pitää sisällään viimeisiä varmistuksia siitä, että rajapinta on oikeanlainen.
Ennen rajapinnan julkaisua, tulisi käydä vielä läpi mahdolliset rahastusmallit, eli kuinka paljon rajapinnan käytöstä veloitetaan ja onko kutsujen määrää rajoitettu joillain tapaa.
Samalla pitäisi käydä läpi, minkälainen SLA rajapinnalle luodaan, jolloin on selvää, mitä tapahtuu mahdollisissa väärinkäytöksissä. (1.)
Neljännessä vaiheessa rajapinnan julkaisun jälkeen tulisi olla jo selvää, miten rajapinnan käyttöä seurataan. Kiinnostavia seurannan kohteita ovat esimerkiksi rajapinnan suori- tuskyky, mitkä applikaatiot käyttävät rajapintaa, mihin kellonaikoihin ja mistä päin maail- maa kutsut tulevat. (1.)
Viidennessä ja samalla viimeisessä vaiheessa rajapinnan käyttö alkaa hahmottua laa- jemmassa mittakaavassa. Tässä vaiheessa API:en hallintomallin tulisi huolehtia siitä,
7
että applikaatioiden kehittäjät saadaan helposti rekisteröityä rajapinnan käyttäjiksi ja että heille on riittävästi tietoa tarjolla, jotta kehitystyö tapahtuisi mahdollisimman tehokkaasti.
Viimeisessä vaiheessa tulisi myös olla selvää, miten rajapinnan vanhan version siirtämi- nen eläkkeelle tapahtuu, jos ja kun uusi versio rajapinnasta julkaistaan. Käyttäjien oh- jaaminen käyttämään uutta versiota tulisi olla mahdollisimman kivuton ja aiheuttaa mah- dollisimman vähän haittaa applikaatioiden kehittäjille. (1.)
3.2 API:en hallintajärjestelmä
API:en hallintajärjestelmä on erillinen ohjelmisto, jonka tarkoituksena on auttaa rajapin- nan kehittäjiä ja omistajia hallinnoimaan rajapintoja. Tavallaan hallintajärjestelmän teh- tävänä on toteuttaa määrittelyjä, joita muodostetaan API:en hallintomalli-vaiheessa.
API:en hallintajärjestelmiä löytyy useilta eri valmistajilta, esimerkkeinä RedHat:n 3scale tai IBM:n API Management.
Se mitä API:en hallintajärjestelmän tulisi pitää sisällään vaihtelee toteutuksesta ja tuot- teesta toiseen ja jokainen yritys haluaisi, että juuri heidän tuotteensa olisi se oikea API:en hallintajärjestelmä. Sekavuutta lisää myös se, että eri tuotteissa saattaa olla komponent- teja, jotka toimivat samaan tapaan, mutta on nimetty hieman eri tavalla tuotteesta toi- seen.
Jos järjestelmistä hakee yhtäläisyyksiä, nousee esiin kahdesta kolmeen komponenttia, joiden toimintatarkoitus on suunnilleen sama järjestelmästä toiseen. Nämä kolme kom- ponenttia ovat API Gateway, API Portal ja API Management Portal. Luokittelun voisi to- dennäköisesti tehdä usealla eri tavalla, mutta nämä kolme osa-aluetta löytyy todennä- köisesti jokaisesta API:en hallintajärjestelmästä. (11;12.)
3.2.1 API-Gateway eli API-yhdyskäytävä
API-yhdyskäytävän tarkoituksena on olla portti verkon ja rajapinnan välillä. Sen tehtä- vänä on suojata rajapintaan liittyviä taustajärjestelmiä, jolloin kutsut, jotka tulevat ver- kosta, kulkevat aina yhdyskäytävän kautta, eivätkä koskaan suoraan taustajärjestelmiin.
Yhdyskäytävä valvoo myös sen kautta kulkevaa liikennettä ja varmistaa, että määriteltyjä sääntöjä noudatetaan. (11.)
Yhdyskäytävä huolehtii siitä, että käyttäjä on autentikoitu ja että esimerkiksi luottamuk- sellinen tieto ei päädy vääriin käsiin. Samalla yhdyskäytävä pyrkii suodattamaan erilaisia rajapintaan kohdistettuja hyökkäyksiä, kuten injektioita ja DDoS-hyökkäyksiä varmistaen että, rajapinnan käyttö ei häiriinny liikaa eivätkä hyökkäykset pääse taustajärjestelmiin asti. Tämä saattaa olla toteutettu esimerkiksi sanomien suodatuksella tai vaikka tietyistä osoitteista tulevien kutsujen hylkäämisellä, kun tietty raja täyttyy. (11.)
Yhdyskäytävän tehtäviin kuuluu myös virheiden hallinta ja raportointi sekä mahdollisesti sanomamuunnokset sekä orkestrointi eri palveluiden välillä. (11.)
3.2.2 Developer portal eli kehittäjäportaali
Kehittäjäportaali on nimenomaisesti suunnattu kehittäjille, eli niille rajapinnan käyttäjille, jotka hyödyntävät rajapintaa omissa palveluissaan tai applikaatioissan. Kehittäjäportaa- lissa on usein tarjolla rajapinnan dokumentaatio, esimerkkikutsuja ja esimerkkikoodeja, joilla kehittäjä pääsee mahdollisimman nopeasti alkuun.
Portaaliin saattaa kuulua myös keskustelufoorumi, jossa pääsee keskustelemaan mui- den kehittäjien ja rajapinnan ylläpitäjien kanssa. Samalla mukana saattaa olla esimer- kiksi tiketöintijärjestelmä, jonka avulla kehittäjä voi tehdä bugien korjauspyyntöjä tai eh- dottaa uusia ominaisuuksia. Portaalista pitäisi löytyä myös jonkinlainen viestintäkanava, jota pitkin rajapinnan kehittäjät ja ylläpitäjät voivat kertoa uusista ominaisuuksista, muu- toksista tai mahdollisista huoltokatkoista. (1.)
Kehittäjäportaalista tulisi löytyä selkeästi myös hinnoittelumallit, mikäli rajapinta ei ole ilmainen, ja mahdollisimman monipuoliset ja helpot maksuvaihtoehdot. Samalla myös rajapinnan SLA tulisi olla helposti saatavilla, jotta kehittäjät tietävät, mistä he maksavat ja mitä rajapinnalla voi tehdä. (1.)
Yksi portaalin tärkein ominaisuus on kehittäjän omien palveluiden tai applikaatioiden re- kisteröiminen rajapinnan käyttöä varten. Usein tämä on hoidettu automaattisesti, eli
9
kehittäjä rekisteröityy rajapinnan käyttäjäksi ja saa käyttöönsä rekisteröintiä tai maksua vastaan esimerkkisi API-avaimen tai jonkun muun autentikointimenetelmän, jonka avulla hän voi kutsua rajapintaa.
Käytännössä kehittäjäportaalin idea on se, että rajapinnan hyödyntäjä saadaan mahdol- lisimman nopeasti käyttämään rajapintaa ja että kaikki olisi mahdollisimman helppoa.
Tästä taas on usein palveluntarjoajalle rahallista hyötyä. Mitä nopeammin ja helpommin kehittäjä pääsee töihin, sitä suurempi todennäköisyys on, että rajapinnasta tulee suo- sittu.
3.2.3 Management portal eli hallintaportaali
Hallintaportaali on nimensä mukaisesti rajapinnan hallintaa varten ja sen pääasiallisina käyttäjinä ovat rajapinnan omistukseen tai toteutukseen liittyvät henkilöt.
Portaalissa on mahdollista esimerkiksi määritellä uusia ympäristöjä rajapintoja varten ja samalla siirtää esimerkiksi kehityksessä oleva rajapinta testiympäristöön tai esimerkiksi luoda tuotantoa varten oma ympäristö, johon testissä oleva rajapinta siirretään, kun se on todettu toimivaksi. (11;13.)
Hallintaportaalissa on myös mahdollista määritellä käyttäjiä ja rooleja tai on mahdollista delegoida tämä tehtävät erilaisille autentikaatio- tai autorisaatiopalvelimille, joiden avulla on mahdollista toteuttaa monipuolisia kirjautumismalleja rajapintaan. Tyypillisesti näissä tapauksissa hyödynnetään joko OAuth-, OpenID- tai SAML-pohjaisia järjestelmiä. (11.)
Portaalissa on usein myös jonkinlaiset analytiikkatyökalut ja järjestelmän monitorointiin liittyviä työkaluja, joilla on mahdollista seurata rajapinnan käyttöä. Analytiikkatyökaluissa saattaa olla mahdollisuus lisätä sääntöjä, joilla seurataan tiettyjä asioita esimerkiksi sa- nomien sisällöstä, joiden avulla voidaan muodostaa kuva kutsuista ja tätä kautta mah- dollisesti löytää myös uusia bisnesmahdollisuuksia. (1.)
4 Frends
Frends on HiQ Internationalin omistama eiPaaS, eli Enterprise Integration Platform as a Service, jonka tarkoituksena on mahdollistaa integraatioiden ja API:en toteutus vähän koodausta vaativalla lähestymistavalla (14) Termi PaaS tarkoittaa, että yritys tarjoaa oh- jelmistoalustaa pilvipalveluna, jolloin asiakkaan ei tarvitse itse huolehtia skaalautuvuu- desta, vaan alusta huolehtii tästä. Esimerkkejä PaaS-palveluista on esimerkiksi Micro- softin Azure ja Googlen App Engine. (15.)
Frendsin tapauksessa eiPaas tarkoittaa, että asiakkaalle tarjotaan integraatioalusta, joka sijaitsee Azuressa, ja että asiakkaan ei tarvitse huolehtia esimerkiksi ylläpidosta tai skaa- lautuvuudesta.
Koska tausta-ajatuksena on minimoida koodin määrä integraatioissa, vähentää Frends kehityskustannuksia ja nopeuttaa tuotteen valmiiksi saattamista samalla vähentäen ope- rointikuluja hyvän monitoroinnin ja loikituksen ansiosta. (14.)
Integraatioalustalla on helppo modernisoida vanhat legacy-järjestelmät, koska Frendsillä on helppo toteuttaa moderneja rajapintoja siihen liittyvien API management -ominaisuuk- sien ansiosta. (14.)
Frends-integraatioalusta on rakennettu .NET-pinon päälle ja pitää sisällään oman run- time-komponentin, jonka tehtävänä on suorittaa alustalla toteutettuja integraatioita. In- tegraatiot ovat käännettyä C#-koodia, ja nämä käännökset on paketoitu NuGet-pake- teiksi. (14.)
NuGet-paketti sisältää kaikki tarvittavat tiedostot komponentin hyödyntämiseen, joka taas mahdollistaa sen, että pakettien jakamiseen voidaan käyttää keskitettyä pakettien hallintaa.
Frendsin eri osat ja integraatiot hyödyntävät paikallisilla asennuksilla Microsoftin Service Bus -toteutusta ja pilviasennuksissa Azure Service Bus -toteutusta.
11
Service Bus on niin sanottu message broker, eli suomeksi tämä voisi tarkoittaa esimer- kiksi sanomanvälittäjä. Sanomanvälittäjää käytetään, jotta saadaan vähennettyä riippu- vuuksia applikaatioiden ja palveluiden väliltä. (16.)
Sanomilla voidaan välittää luotettavasti ja asynkronisesti dataa ja tiloja. Data välitetään applikaatioiden tai palveluiden välillä sanomina, jotka ovat binäärimuodossa ja voivat si- sältää esimerkiksi tekstiä, JSON-muotoista dataa tai XML-sanomia. (16.)
Etuna asynkronisessa viestinvälityksessä on se, että applikaatioiden tai palveluiden ei tarvitse olla samaan aikaan päällä, vaan ne saavat viestin siinä vaiheessa, kun ilmesty- vät jälleen käyttämään sanomapalvelua. (16.)
Service Busin hyödyntäminen mahdollistaa sen, että Frendsllä on mahdollista toteuttaa erityyppisiä integraatioratkaisuja, esimerkiksi hybridi ja multi-cloud toteutuksia. (14.)
Hybridi-ratkaisuissa integraatio voi sijaita osin pilvessä ja osin paikallisella palvelimella ja nämä osat toimivat yhtenä kokonaisuutena johtuen juuri Service Busin hyödyntämi- sestä.
Multicloud-toteutuksella taas tarkoitetaan sitä, että palveluiden ei tarvitse sijaita saman palveluntarjoajan pilvessä, vaan että on mahdollista hyödyntää käytännössä mitä ta- hansa palvelua, kuten kuvassa 1 on esitetty.
Kuva 1 iPaas Environment
Integraatioalustalla on myös helppo rakentaa niin sanottuja komposiittirajapintoja eli yh- distää kaksi tai useampi rajapinta yhden rajapinnan taakse. Kutsujalle tämä näyttää siltä, että kysely lähetetään yhteen paikaan ja vastaus tulee yhdestä paikasta, vaikka rajapin- nan taustalla saattaa tapahtua useita kutsuja. Rajapinnan taustalla on mahdollista myös samanaikaisesti toteuttaa esimerkiksi tietokantakutsuja, joiden tuloksilla on mahdollista rikastuttaa asiakkaalle lähetettävää paluusanomaa.
Frendsillä voi toteuttaa myös tavallisia integraatioita ja siitä löytyvät työkalut esimerkiksi tiedostonsiirtoja ja tietokantakutsuja varten.
Integraatioden toteutus tapahtuu FrendsUI:n kautta, joka on pilveen tai paikalliselle pal- velimelle asennettu web-sovellus, eli käytännössä kaikki kehitystyö tapahtuu selaimen kautta.
4.1 Frends arkkitehtuuri
Frends hyödyntää Miniservice-pohjaista lähestymistapaa ja kolmikerroksista integraatio- arkkitehtuuria, joiden avulla on mahdollista toteuttaa erilaisia integraatiotarpeita (kuva 2).
13
Kuva 2 Frends arkkitehtuuri
Ensimmäisessä kerroksessa on triggerit eli käynnistimet, joilla integraatio käynnistyy.
Käynnistimiä on useita erilaisia, ja käynnistyskäsky voi tulla esimerkiksi HTTP-triggerin kautta, jolloin Frends käynnistää integraation tietynlaisen sanoman saapuessa käynnis- timelle. Vaihtoehtona on myös esimerkiksi queue-käynnistin, joka on mahdollista kytkeä erilaisiin jonoratkaisuihin, joiden kautta herätteet saapuvat.
Seuraavassa kerroksessa on suorittava osa, jossa itse integraatio ajetaan. Integraation toteutuksessa on mahdollista käyttää erialisia suunnittelumalleja ja toteutustapoja, eikä toteutus ole sidottu vain yhteen tapaan.
Alimmalla tasolla suoritetaan kutsut aiemmin mainittuihin minipalveluihin, jotka voivat koostua hyvinkin erilaisista palasista. Palvelut voivat olla esimerkiksi mikropalveluita, le- gacy-järjestelmiä tai moderneja pilvipalveluita ja rajapintoja. Jos palvelu vaatii erikoisem- man yhteystavan, on tämä mahdollista toteuttaa itse joko rakentamalla alustalle integ- raatio, joka hoitaa yhteyden tai ohjelmoimalla oman tehtävän eli taskin yhteydenpitoa varten.
API-arkkitehtuuri on toteutettu käytännössä samalla tavalla (kuva 3). Lisänä on ainoas- taan ylimääräinen turvallisuuskerros API:en hallintaa ja API:en julkaisua varten. (14.)
Kuva 3 Frends API -arkkitehtuuri
4.2 Integraatioiden toteutus, käynnistys ja suoritus
Frendsissä integraatiot toteutetaan graafisella BPMN-notaatiolla, joka on vuokaaviome- netelmä, jonka avulla kuvataan bisnesprosesseja. BPMN:ä käytetään kuvaamaan pro- sessi sarjana bisnesaktiviteetteja ja näiden välisiä tietovirtoja, joita vaaditaan prosessin loppuun viemiseen. (17.)
Esimerkkinä tällaisesta prosessista on kuvassa 4 kuvattu puhelimen ostaminen, johon liittyy erilaisia ehtoja puhelimien saatavuuteen ja käytettävissä olevaan rahamäärään.
Ero Frendsissä käytetyn notaation ja esimerkkikuvan välillä on, että Frends-toteutuk- sissa ei käytetä kuvassa esiintyviä uimaratoja.
15
Kuva 4 Buying Phone BPMN Template
Integraatio tai Frendsin tapauksessa prosessi piirretään web-sovelluksen avulla piirto- alustalle käyttäen hyödyksi BPMN-notaatiota valitsemalla työkaluriviltä haluttu tapah- tuma, aktiviteetti tai portti, joiden välille piirretään tietovirrat (kuva 5).
Kuva 5 Frends UI
Frends-prosessi koostuu yhdestä tai useammasta aktiviteetistä, joita kuvaavat käynnis- timet, eli erilaiset triggerit, joiden kautta prosessi käynnistyy. Yhteen prosessiin on mah- dollista lisätä useampia käynnistimiä ja on mahdollista, että prosessi käynnistetään esi- merkiksi ajastimella tiettyyn kellonaikaan tai että prosessi käynnistyy, kun sitä kutsutaan verkon kautta.
Esimerkkinä tällaisesta prosessista on kuva 6, jossa on yksi tehtävä eli task ja kolme käynnistintä. Esimerkkiprosessin käynnistyy joko http-kutsulla, ajastimella kymmenen minuutin välien, tai sen voi käynnistää käsin Frendsin UI:n kautta.
Kuva 6 Yksinkertainen Frends-prosessi, jossa on kolme erilaista käynnistintä ja yksi tehtävä.
Käynnistyksen jälkeen prosessin suoritusta ohjataan erilaisella ehdolla ja silmukoilla, ku- ten for each -silmukoilla tai ehdollisilla haarautumisilla. Prosessiin on myös mahdollista lisätä scope-elementtejä, jos halutaan koota tietyt osat yhdeksi kokonaisuudeksi. Scope- elementtejä käytetä usein myös prosessin virheidenhallinnan toteutukseen. Scope-ele- mentti toimii niin, että elementin sisällä määritellyt muuttujat ja tehtävien tulokset eivät näy elementin ulkopuolelle. Scope-elementistä voi kuitenkin palauttaa tuloksen, jota ele- mentin ulkopuolella olevat osat voivat käsitellä.
Esimerkki for-each -silmukan käytöstä ja scope-elementeistä löytyy kuvasta 7. Kuvassa on kuvattu osa prosessia, jossa for-each-silmukka on laitettu scope-elementin sisälle
17
mahdollisten virheiden varalta, jolloin virheen sattuessa poikkeus voidaan ottaa kiinni ja lähettää tieto suorituksen epäonnistumisesta eteenpäin.
Silmukassa käsitellään rivejä ja jokaiselle riville tehdään rikastus, eli dataan lisätään jo- tain tai sitä muokataan jollain tavalla ja tämän jälkeen rivi lisätään muuttujaan. Silmukan jälkeen muuttuja palautetaan scope-elementistä poistumisen yhteydessä, jolloin rikas- tettua tietoa on mahdollista käyttää myös muualla prosessissa.
Kuva 7 Frends-prosessi, jossa on kuvattu Scope-elementin ja For each-elementin käyttöä
Piirtotyökalut sisältävät myös esimerkiksi throw- ja catch-elementit, jotka toimivat käy- tännössä samaan tapaan kuin ohjelmointikielissä eli throw-elementillä voidaan heittää virhe ja catch-elementillä voidaan ottaa virhe kiinni ja toteuttaa sen alle osio, jossa virhe käsitellään tai tehdään mahdollisia muita toimenpiteitä. Elementit löytyvät kuvasta 7, jossa on esitetty myös yksinkertainen virheenhallinta, jossa poikkeus otetaan kiinni ja
virhe lokitetaan aliprosessin avulla ja tämän jälkeen heitetään virhe, jolloin virheellinen suoritus tulee näkymään myös Frends UI:ssa.
Prosessin tärkein elementti on task, joka nimensä mukaisesti tekee jonkun tehtävän.
Tehtävä voi olla käytännössä melkein mitä tahansa, ja usein se on esimerkiksi sanoma- muunnos, tietokantaan kirjoitus tai tiedostonsiirto. Kuvassa 8 on esitelty Frendsin Wri- teBytes-tehtävä, joka nimensä mukaisesti mahdollistaa byte-taulukon kirjoittamisen le- vylle tai esimerkiksi tiedostojakoon. Tehtävällä voi olla useita parametrejä, kuten ku- vassa näkyvä Content bytes ja Path, mutta on myös mahdollista, että tehtävä ei ota vas- taan mitään parametrejä kuten kuvassa 6 esitelty AlwaysTrue-tehtävä, joka nimensä mu- kaisesti palauttaa aina arvon true.
Kuva 8 Frends WriteBytes-task
Frendsin tehtävät, kuten myös itse integraatioalusta pohjautuu Microsoftin .NET-ohjel- mistokomponenttikirjastoon, ja tehtävät ovat käytännössä C#-ohjelmointikielellä toteutet- tuja staattisia metodeja, joista on käännetty DLL eli dynamic-link library, joka on Micro- softin toteutus jaetuista kirjastoista.
19
Jaettu kirjasto paketoidaan erilliseksi NuGet-paketiksi ja pakettiin kuluu Frendsin tapauk- sessa usein käännetty DLL sekä XML-tiedosto, jossa on esitelty tehtävän parametrit ja kuvattu tehtävän toiminta. Paketti saattaa pitää sisällään myös kolmannen osapuolen kirjastoja, joita tarvitaan tehtävän suorittamiseen.
Jos jo olemassa olevat tehtävät eivät riitä, on tehtävien toteutus hyvin suoraviivaista ja niitä on helppo luoda lisää.
Aivan kaikkia toimintoja ei ole pakko toteuttaa erillisillä tehtävillä, vaan Frendsissä on myös kaksi erilaista tapaa tuoda koodia osaksi prosessia ilman, että siitä pitää muodos- taa erillinen tehtävä.
Expression-elementti on tarkoitettu yleensä tapauksia varten, joissa yksi rivi koodia on riittävästi, esimerkiksi tehtävän paluuarvon talteenotto ja sen muokkaaminen. Expres- sion-elementissä on mahdollista käyttää myös esimerkiksi LINQ:iä, joka on C#-kielestä löytyvä komponentti, joka mahdollistaa SQL-kyselykieltä muistuttavien kyselyiden toteut- tamisen. Kyselyillä on mahdollista hakea dataa esimerkiksi erilaisista C#-kieleen liitty- vistä kokoelmista, kuten listoista.
C#-statement-elementti taas mahdollistaa useamman koodirivin käyttämisen ja C#-sta- tement elementissä on mahdollista toteuttaa esimerkiksi omia metodeja, mutta ei kuiten- kaan omia luokkia.
Kuvassa 9 on esitelty Expression-elementin käyttöä. Esimerkissä määritellään muuttuja customerGroups johon, tallennetaan kuvassa 9 olevan Expression-kentän LINQ-kyselyn tulos. Tässä tapauksessa GetCustomers-tehtävä on palauttanut joukon asiakkaita ja LINQ-kyselyllä lajitellaan asiakkaat tuhannen kappaleen ryhmiin.
Kuva 9 Expression-elementti ja sen sisältämä LINQ-lause
Jos prosessin rakennusvaiheessa huomataan, että joku tietty osa prosessia toistuu use- ammassa kohtaa tai että joku osa prosessia on toteutettu valmiiksi toisaalla, on proses- sissa mahdollista käyttää myös aliprosesseja.
Aliprosessi on käytännössä vastaavanlainen kuin ”pääprosessi”, mutta sen käynnistä- mistä ei voi tehdä samoilla käynnistimillä kuin pääprosessia, vaan se käynnistetään pääprosessin kautta. Usein käynnistyksen yhteydessä aliprosessille annetaan paramet- rejä, joiden mukaan aliprosessin suoritus etenee. Kun aliprosessi käynnistetään, suorit- taa se osuutensa loppuun ja palauttaa lopputuleman takaisin pääprosessille.
Kun prosessi on toteutettu valmiiksi ja tallennettu, aloitetaan prosessin kääntäminen ja NuGet-paketin luominen. Kuvassa 10 on kuvattu se, mitä tallennuksen jälkeen tapahtuu, eli ensimmäisessä vaiheessa prosessi käännetään ja siitä luodaan NuGet-paketti. Tä- män jälkeen prosessi tallennetaan konfigurointitietokantaan ja luotu NuGet-paketti vie- dään yleiseen pakettisäilöön. Pakettisäilöön viennin jälkeen service busin kautta lähtee tieto kaikille ympäristöön kuuluville agenteille, että uusi prosessi on saatavilla (18).
21
Kuva 10 Mitä tapahtuu, kun käyttäjä on tallentanut prosessin.
Kun service busin kautta saapuva viesti tavoittaa agentin, käy se kuvan 11 mukaisesti lataamassa NuGet-paketin pakettisäilöstä ja kopioi sekä asentaa prosessin omaan pai- kalliseen prosessisäilöön, jonka jälkeen prosessin suorittaminen on mahdollista. Vaikka prosessi kopioidaankin jokaisen agentin paikalliseen prosessisäilöön, täytyy se vielä siir- tää ja erikseen aktivoida eri ympäristöissä, joka mahdollistaa sen, että tuotannossa ja esimerkiksi testissä voi olla eri versiot prosesseista. (18.)
Kuva 11 Mitä tapahtuu, kun prosessi on siirretty pakettisäilöön
4.3 Agentit
Agentti on käytännössä Windows-palvelu, joka suorittaa prosesseja. Agentit ovat itse- näisiä osia, eivätkä ole riippuvaisia esimerkiksi Frendsin UI:sta, vaan ne suorittavat teh- täviä taustalla, oli UI aktiivisena tai ei. (18.)
Agentit keskustelevat muiden komponenttien kanssa Service bus:n välityksellä. Jos agentti on asennettu pilveen, käytetään Azure Service Bus -väylää, kun taas on-premise- asennuksessa käytetään tavallista Service Busia.
Service Bus -väylän hyödyntämisen ansiosta hybridiympäristössä on mahdollista toteut- taa prosesseja, joissa prosessiin liittyviä aliprosesseja ajetaan eri ympäristössä kuin itse pääprosessia. Esimerkiksi toteutus, jossa aliprosessia ajetaan pilviympäristössä ja pääprosessia on-premise -ympäristössä, on mahdollinen (18.).
Agentit on lisätty aina yhteen agenttiryhmään, jossa voi olla yksi tai useampi agentti.
(18.) Usein ryhmät on rakennettu niin, että esimerkiksi kehitys- ja testiympäristössä on yksi agentti ja tuotantoympäristössä on useampi agentti. Tosin myös muunlaiset konfi- guraatiot ovat mahdollisia.
23
Kuvassa 12 on kuvattu yksi mahdollinen konfiguraatio, jossa tuotantoympäristölle on määritelty kaksi agenttiryhmää: CloudProd ja OnPremProd. Tässä tapauksessa molem- missa ryhmissä on kaksi agenttia. OnPremProd-ryhmän agentit ajavat integraatioita pai- kallisella palvelimella, kun taas CloudProd-ryhmän agentit toimivat pilvessä.
Kuva 12 Tuotantoympäristön agenttiryhmät
Jos yhdessä ryhmässä on useampi kuin yksi agentti, muodostavat nämä niin sanotun agenttifarmin, jossa agentit jakavat tilan ja yhteisen tietokannan. Tästä hyötynä on se, että agentit pystyvät jakamaan tehtäviä keskenään, jos suoritusten määrä kasvaa. (19.)
Agentti on mahdollista asentaa kahteen eri tilaan. Ensimmäinen tila on edellä kuvailtu prosessin suoritukseen käytettävä agentti ja toinen tila on niin sanottu ”gateway”-tila, jossa agentti toimii API-yhdyskäytävänä (20).
Yhdyskäytävä-agentti paljastaa ulkomaailmalle minkä tahansa HTTP- tai API-triggerin, autentikoi sitä vasten tehdyt kutsut ja välittää eteenpäin ne suorittaville agenteille, jolloin saadaan ylimääräinen kerros tietoturvaa palveluiden välille sekä vähennettyä suoritta- vien agenttien kuormaa. Yhdyskäytävä-agentti osaa myös rajoittaa kutsujen määrää ja
suorittaa pienimuotoista kuormantasausta. Käytännössä yhdyskäytäväagenttia ei kui- tenkaan ole pakko asentaa, vaan tavallinen prosesseja suorittava agentti osaa myös tehdä kaiken sen, mitä gateway-tyyppinen agenttikin. (20.)
5 Yksinkertaisen rajapinna toteuttamien Frendsillä
Insinöörityön tarkoituksena oli tutustua API Managementiin ja siihen, kuinka tämä on to- teutettu Frends-integraatioalustalla. Koska toteutettavaa rajapintaa ei ollut tarkoitus lai- taa tuotantokäyttöön, oli työssä mahdollista ottaa joitain vapauksia, eikä noudattaa täysin API Managementin periaatteita. Samalla huomioitiin myös, että Frends ei ole puhtaasti API Management -järjestelmä, joten kaikkia API management -järjestelmiin liittyviä kom- ponentteja ei ollut mahdollista käyttää.
Rajapinnan toteutuksessa ei pyritty mahdollisimman suureen suorituskykyyn, vaan tar- koituksena oli tutkia, miten eri web-palveluiden yhdistäminen ja orkestrointi näiden pal- veluiden välillä onnistuu. Valmis toteutus tulisi olemaan niin sanottu komposiittirajapinta, joka näkyisi kutsujalle yhtenä rajapintana, mutta taustalla suoritettaisiin kutsuja muihin rajapintoihin ja näiden avulla saataisiin aikaan joitain, mitä yksittäiset rajapinnat eivät pystyisi yksinään tuottamaan.
Rajapinnan idea oli hyvin yksinkertainen. Tarkoituksena oli hakea yhdestä palvelusta kuluttajaindeksidataa, joka vietäisiin toiseen palveluun, jossa datasta muodostetaan dia- grammi ja tämä diagrammi tallennetaan kolmanteen palveluun. Tämän lisäksi toteutet- taisiin endpoint eli päätepiste, josta olisi mahdollista hakea latauslinkki aiemmin muo- dostettuun diagrammiin, sekä kolmas päätepiste, jonka kautta diagrammi olisi mahdol- lista poistaa. Käytännössä kaikki päätepisteet voitiin yhdistää yhdeksi, johon tultaisiin käyttämään eri http-metodeja.
5.1 Taustapalvelut
Rajapintaa varten valitut web-palvelut, joita aiottiin hyödyntää, olivat Imagecharts WebservceX.net ja Dropbox, joihin kaikkiin oli tarjolla julkinen rajapinta. Tavoitteena oli
25
löytää myös SOAP-tyyppinen rajapinta, mutta tällaisia oli ilmaisena tarjolla melko vähän, ja ne, mitä oli tarjolla, eivät soveltuneet tämän rajapinnan toteutukseen.
5.1.1 Imagecharts
Imagecharts on korvaava vaihtoehto Googlen Image Charts API:lle, jonka Google ajoi alas vuonna 2017. Imagecharts tarjoaa rajapinnan, jonka kautta on mahdollista muodos- taa erilaisia diagrammeja ja muita graafisia elementtejä, kuten QR-koodeja.
Palvelu toimii lähettämällä http-kutsun yhteydessä diagrammin sisältämä data, diagram- min typpi ja muut parametrit, query-parametreinä palveluun. Jos kutsu on oikein muo- toiltu, palauttaa rajapinta datasta muodostetun diagrammin PNG-muotoisena kuvana.
Palvelusta oli tarjolla kolmenlaista eri maksumallia: ilmainen, enterprise ja on-prem, joista kaksi viimeistä oli maksullisia ja sisälsi ominaisuuksia, joita ilmaisessa mallissa ei ollut. Ilmaisversiota testatessa kävi kuitenkin ilmi, että ei olisi mitään tarvetta maksaa kalliimmasta versiosta, vaan toteutusta varten riittäisi ilmainen versio. Toki jos rajapinta olisi oikeasti tarkoitettu tuotantokäyttöön, olisi maksullisia vaihtoehtoja syytä harkita.
5.1.2 WebserviceX
WebserviceX-palvelusta ei ollut paljoakaan taustatietoa tarjolla, ainoastaan että palvelun yhteystiedot antoivat Cloud Computing Technologies Ltd -yrityksen osoitteen, joka si- jaitsi Isossa-Britanniassa. Palvelusta oli mahdollista hakea tietoja esimerkiksi korkojen muutoksista, valuuttakursseista ja erilaisista indekseistä. Haku oli toteutettu normaalina REST-tyyppisenä kyselynä, ja rajapinta palautti datan JSON-muodossa. Datan oikeelli- suudesta ei ollut mitään takeita, mutta toteutuksen kannalta sillä ei ollut merkitystä, vaan tavoitteena oli saada palvelut yhdistettyä ja luotua saadusta datasta diagrammeja.
5.1.3 Dropbox
Dropbox on yhdysvaltalainen tiedostojen verkkotallennuspalvelu. Dropbox inc. tarjoaa tiedostojen säilytystä ja tietojen synkronointia esimerkiksi tietokoneen ja puhelimen vä- lillä. Dropbox tarjoaa viittä erilaista tiliä, joista yksi on suunnattu erityisesti tiimeille ja
yrityksille. Erona tileillä on muun muassa säilytystilan määrä ja tiedostojen vanhojen ver- sioiden säilytyksellä.
Palvelusta on olemassa usealle alustalle oma asiakasohjelmisto, jonka voi asentaa suo- raan käytettävälle laitteelle. Laiteeseen luodaan hakemisto, joka synkronoidaan Dropbo- xin pilvipalvelun kanssa, jolloin sinne laitetut tiedostot ovat aina saatavilla. Dropbox tar- joaa myös mahdollisuuden käsitellä tiedostoja API-rajapinnan kautta, jolloin esimerkiksi tiedostojen tallennus onnistuu suoraan http-kutsuilla.
Dropbox tarjoaa myös API Explorer -ominaisuuden, jonka kautta on mahdollista kokeilla rajapintakutsuja omalla tunnuksella. Palvelusta on mahdollista saada myös koodiesi- merkkejä, joiden avulla kutsut voi toteuttaa omaan applikaatioon.
5.2 Suunnittelu
Insinöörityön toteutus aloitettiin tutkimalla, minkälaisia kutsuja palveluihin oli mahdollista lähettää ja tarvittiinko palveluita varten rekisteröintejä ja varmennusavaimien luontia.
Ainoastaan Dropbox vaati tunnuksen sekä oman applikaation rekisteröinnin heidän jär- jestelmiinsä. Dropboxin hyvänä puolena oli myös se, että jos applikaatio käytti ainoas- taan rekisteröityä hakemistoa, autorisointiin riitti pelkkä OAuth access token, jonka sai luotua palvelun kautta, eikä tässä tapauksessa tarvinnut toteuttaa monimutkaisempia OAuth-ratkaisuja.
Dropbox sisälsi myös oman API Explorer -palvelun, jossa oli mahdollista testata kutsuja etukäteen ja opiskella rajapinnan toimintaa ennen oman sovelluksen toteutusta. Ku- vassa 13 testattavana on datan poisto Dropbox-palvelusta hyödyntäen heidän rajapin- taansa.
API Explorer käytännössä generoi kutsut valmiiksi, jolloin käyttäjän tehtäväksi jäi lähinnä testata toimivatko kutsut kuten niiden pitäisi, sekä kopioida esimerkistä tiedot mahdolli- seen omaan sovellukseen. Pelkän http-pyynnön (kuva 13) lisäksi API Explorerilla oli mahdollista luoda valmiita Python-koodin pätkiä, jolla kutsuja voisi toteuttaa ohjelmalli- sesti.
27
Kuva 13 Dropbox API Explorer
WebserviceX-palvelusta taas ei löytynyt samanlaisia hienouksia kuin Dropbox-palve- lusta. Päätepisteitä oli tarjolla satoja, jotka käytännössä esitettiin yhtenä pitkänä listana ja listasta oli hyvin vaikea löytää mitään.
Kuvasta 14 näkee, miten palvelu oli dokumentoitu. Käytännössä kutsujalle tarjottiin ai- noastaan tieto siitä, miten päätepistettä tulisi kutsua, lista esimerkkidatasta, sekä mah- dollisuus kopioida SDK-välilehdeltä valmiita kooditoteutuksia rajapinnan kutsumista var- ten.
Tässä vaiheessa myös huomattiin, että toteutuksen päätepisteet eivät tukeneet datan määrän rajaamista, vaan palvelu palauttaisi aina kerätyn aineiston vuosien 1960 – 2007 väliltä.
Ongelma päätettiin kiertää valitsemalla toinen päätepiste, josta olisi mahdollista hakea kuluttajahintaindeksimuutokset neljännesvuosittain, jolloin datan määrää saataisiin
pienennettyä ja data voitaisiin entisestään rajata lisäämällä muutama rivi koodia palvelua kutsuvaan prosessiin.
Kuva 14 Yhden WebserviceX-palvelun päätepisteen tiedot
Imagecharts-palvelu tarjosi hyvän dokumentaation, ja tämän palvelun suhteen päästiin nopeasti alkuun. Kuvassa 15 näkyy, kuinka rajapintaa pystyi testaamaan helposti esi- merkiksi Postman-ohjelmalla. Kuvassa näkyvä kysely on kopioitu suoraan Imagecharts- palvelun esimerkkikutsuista, ja tämä kysely otettiin pohjaksi, kun aloitettiin toteuttaa
29
omaa kyselyä rajapintaa vasten. Postmanissa oli helppo vaihtaa parametrien tyyppejä ja arvoja ja lopputuloksen pystyi näkemään saman tien.
Kuva 15 Postman-ohjelmalla suoritettu alustava rajapinnan testaus
Alustavien Postmanilla suoritettujen testien jälkeen päädyttiin ratkaisuun, jossa toteutet- taisiin viivadiagrammi WebserviceX-palvelusta saatavasta datasta, jossa x-akselilla olisi vuosiluku sekä kuukausi ja y-akselilla esitettäisiin indeksin datapisteet.
Kun palvelut oli testattu ja tutkittu, mitä kaikkea olisi mahdollista toteuttaa, päätettiin Frensin puolelle toteuttaa kolme päätepistettä. Samalla tämä tarkoittaisi myös sitä, että jokaista päätepistettä varten täytyisi toteuttaa myös oma integraatioprosessi.
Kaikkien kolmen päätepisteen nimi tulisi olemaan sama eli ” /v1/consumerIndex”, mutta näitä tultaisiin kutsumaan eri http-metodeilla riippuen siitä, haluttaisiinko luoda, hakea vaiko poistaa dataa. Käytettävät http-metodit tulisivat tässä tapauksessa olemaan POST, GET ja DELETE.
Ensimmäinen päätepiste ja samalla ensimmäinen prosessi, jolla luotaisiin itse diagrammi olisi POST-tyyppinen. Prosessin toimintaa on kuvattu kuvassa 16, eli prosessi
käynnistyisi http-käynnistimellä ja tälle annettaisiin parametreinä maakoodi ja aikaväli, jolta data halutaan diagrammiin. Tämän jälkeen prosessi suorittasi kutsun Webservi- ceX:n rajapintaan erillisellä aliprosessilla (kuva 17) ja pilkkoisi datan annetun aikavälin mukaan.
Pilkottu data kuljetettaisiin Imagecharts-palveluun ja paluuviestinä saatu diagrammi tal- lennettaisiin Dropboxiin. Tallennuksessa tiedostonnimenä käytettäisiin GUID:a, joka luo- taisiin prosessin suorituksen alussa, ja tämä GUID palautetaan kyselijälle, kun tiedoston tallennus valmistuisi.
31
Kuva 16 POST-päätepisteen toiminta
Kuva 17 POST-prosessiin liittyvän aliprosessin toiminta
Toinen toteutettava päätepiste/prosessi tulisi olemaan GET-tyyppinen. Tämä tulisi hyö- dyntämään POST-päätepisteestä saatua GUIDa, joka toimisi linkkinä luotuun diagram- miin.
Päätepisteelle annettaisiin parametreinä aiemmin luotu GUID, jonka perusteella prosessi osaisi luoda Dropbox API:n avulla latauslinkin tiedostoon. Latauslinkki palautettaisiin kut- sujalle, jos prosessin suoritus onnistuisi. Latauslinkin avulla kutsujan olisi mahdollista ladata aiemmin muodostettu tiedosto omalle koneelle.
Prosessin toimintaa on kuvattu kuvassa 18 ja kuvassa 19. Kuvassa 19 esitetään pääpro- sessiin liittyvän aliprosessin toimintaa. Aliprosessin tehtävänä on käydä tarkistamassa Dropboxin rajapinnan kautta, onko tiedosto jo olemassa, ennen latauslinkin luomista.
33
Kuva 18 GET-päätepisteen toiminta
Kuva 19 GET-prosessiin liittyvän aliprosessin toiminta
Viimeinen päätepiste tulisi olemaan tyyppiä DELETE, joka nimensä mukaisesti poistaisi aiemmin POST-metodilla luodun tiedoston.
Parametreina päätepiste ottaisi vastaan tiedostoon tiedoston luonnissa luodun GUID:n, jonka avulla tiedosto saataisiin poistettua Dropboxista. Prosessia on kuvattu kuvassa 20, ja prosessi käyttäisi samaa aliprosessia tiedoston etsimiseen kuin GET-päätepiste.
(Kuva 19.)
35
Kuva 20 DELETE-päätepisteen toiminta
Frends-prosessien suunnittelun jälkeen päästiin itse rajapinnan toteutuksen suunnitte- luun. Rajapinnan suunnittelussa täytyi ottaa huomioon autentikointi, mahdollinen raja- pinnan käytön rajaaminen, sisään- ja ulosmenevät sanomat, virheviestit sekä virheiden hallinta.
Koska rajapinta ei tulisi tuotantokäyttöön, eikä sitä tultaisi pommittamaan suurella mää- rällä kutsuja, ei rajapintakutsujen määrää nähty tarpeelliseksi rajata. Kutsujen määrä tu- lisi pysymään maltillisena, eikä taustajärjestelmille aiheutuisi liikaa kuormaa.
Autentikoinnin toteutuksessa päädyttiin käytännön syistä API-key-autentikaatioon. To- teutusta varten tämä olisi kaikkein helpoin toteuttaa, eikä vaatisi ylimääräisiä asennuksia tai tilejä. Muita vaihtoehtoja olisi esimerkiksi Basic Authentication, sertifikaatit ja OAuth2.
Rajapinnan sanomat tulisivat olemaan hyvin yksinkertaisia. Ainoa sisään tuleva sanoma tulisi olemaan ensimmäisessä prosessissa, jossa datan määrää pystyi rajaamaan para- metrein. Muissa prosesseissa parametrejä ei ollut kuin yksi kappale per prosessi, joten parametrit päätettiin tuoda osana polkua, niin sanottuina path-parametreinä.
Path-parametrit ovat osa URL:a, ja ne usein esitetään muodossa: /osa_pol- kua/{id}/osa_polkua/{id2}. Eli rajapintaa kutsuttaessa aaltosulkeet ja niiden sisällä olevat parametrit korvataan oikeilla arvoilla. Esimerkkipolusta voisi tulla seuraavanlainen:
/osa_polkua/14/osa_polkua/1234.
Virheiden suhteen päädyttiin ratkaisuun, jossa sanoman muoto olisi aina samanlainen riippumatta siitä, onnistuiko vaiko epäonnistuiko kutsu. Sanoman mukana palautuisi aina samanmuotoinen sanoma, jossa olisi http-statuskoodi sekä kenttä viestille.
Onnistuneissa kutsuissa viesti sisältäisi joko tiedoston nimen tai tiedoston latauslinkin sekä statuskoodin 200. Virheellisissä suorituksissa, viestissä palautettaisiin joko status- koodi 500 sekä viesti ”internal server error” tai jos mahdollista viesti, jossa kerrottaisin virheen oikea syy.
37
Oikea virheilmoitus palautuisi tilanteissa, joissa Dropboxista eli löytyisi tiedostoa anne- tuilla parametreillä, WebserviceX-palvelu ei palauttasi riittävästi dataa, sanoman vali- dointi epäonnistuisi tai API-avain ei olisi kelvollinen. API-avaimen tarkistus tapahtuu Frendsin puolesta automaattisesti, joten tähän ei myöskään voinut vaikuttaa.
Jotta rajapintaan tehtyjä kutsuja olisi helpompi seurata, päätettiin rajapintakuvaukseen lisätä myös mahdollisuus liittää kutsuun mukaan X-Request-ID-header, jonka avulla kut- suja voitaisiin seurata. Header palautettaisiin rajapinnan kutsujalle onnistuneen sekä epäonnistuneen kyselyn vastauksen mukana.
5.3 Toteutus
Toteutus aloitettiin rajapintakuvauksen luomisella. Frends tukee OpenAPI-spesifikaa- tiota, joka tunnettiin aiemmin nimellä Swagger RESTful API Documentation Specifi- cation. Open API -spesifikaatiolla voidaan luoda koneluettavia rajapintakuvauksia, joista käy ilmi, miten rajapintaa käytetään, minkälaisia sanomia sille voi syöttää, millä tavalla rajapinta vastaa ja niin edelleen.
Rajapintakuvausta varten Frendsiin on integroitu Swagger Editor, jonka avulla rajapinta- kuvakset voi luoda, samalla kun editori antaa palautetta dokumentin rakenteesta tai lä- hinnä mahdollisista virheistä, joita dokumentista löytyy (kuva 21). Editori rakentaa sa- malla myös esimerkkikutsut ja sanomat kuvauksen perusteella ja editorin yhteydessä olevalla Swagger UI:lla on mahdollista testata kutsuja, kunhan kuvaus on ensin tallen- nettu kehitysympäristöön.
Rajapintakuvauksen voi toteuttaa kahdella eri merkintätavalla, jotka ovat YAML ja JSON.
YAML on näistä huomattavasti käyttäjäystävällisempi, joten kuvaus toteutettiin käyttä- mällä kyseistä merkintäkieltä (kuva 22).
Kuva 21 Swagger editor
39
Kuva 22 Esimerkki Open API -spesifikaatiosta. Vasemmalla JSON-kuvaus ja oikealla YAML-kuvaus.
Rajapintakuvauksen toteutus aloitettiin hahmottelemalla rajapinnassa käytettävät http- metodit, päätepisteet ja rajapinnan polku (kuva 22). Rajapinnan versionnumero oli tar- koitus sisällyttää päätepisteen polkuun. Ajatuksena oli, että polusta olisi suoraan nähnyt käytettävän rajapinnan versionumeron, eli osoitteeksi olisi muodostunut palvelimen osoite, jonka perään olisi liitetty ”/v1/consumerIndex”.
Kuva 23 Rajapintakuvauksen hahmotelma
Kun rajapintakuvaus oli toteutettu loppuun, käyty läpi ja todettu, että tarvittavat tiedot ovat paikallaan, tallennettiin rajapintakuvaus HiQ:n Frends-ympäristöön, joka oli tarkoi- tettu Frendsin opiskeluun.
Rajapintakuvauksen tallennuksen jälkeen rajapinnalle täytyi luoda vielä oma API-avain, sekä lisätä avaimeen rajapinnan käyttöä rajaavat säännöt. Avaimen ja sääntöjen luonti oli hyvin suoraviivaista ja vaati muutaman hiirenpainalluksen.
Avaimelle täytyi antaa nimi, valita mihin ympäristöön avain kelpasi sekä mikä sääntöko- koelma yhdistettäisiin avaimeen ja haluttaisiinko avaimelle asettaa rajoituksia kutsujen määrän suhteen (kuva 24).
41
Kuva 24 API-avaimen määrittely
Sääntökokoelmaa varten luotiin rajoitukset koskemaan DemoAPI/v1-polkua, johon sal- littiin http-metodit POST, GET ja DELETE. Muilla metodeilla kutsuttaessa vastaukseksi tulisi statuskoodi 404. Sääntökokoelma linkitettiin vielä aiemmin luotuun API-avaimeen, jonka jälkeen prosessien toteutus voitiin aloittaa (kuva 25).
Kuva 25 Rajapinnan sääntöjen määritteleminen
5.3.1 POST-Prosessi/päätepiste
Kun rajapintakuvaus oli toteutettu, oli aika aloittaa itse prosessien toteutus, eli toiminnal- lisuus rajapintakuvauksen taustalla.
Rajapintakuvauksen tallennuksen jälkeen tulisi jokaiselle pääte- ja http-metodiyhdistel- mälle luoda oma prosessi. Kun rajapintaa kutsuttaisiin, Frends ohjaa kutsun oikealle pro- sessille, joka tekisi tarvittavat sanomavalidoinnit, suorittasi mahdolliset sanomamuun- nokset, kutsuisi valittuja taustapalveluita ja palauttasi rajapinnan kutsujalle rajapintaku- vauksen mukaisen vastauksen.
Prosessit tulisi myös linkittää oikeisiin päätepisteisiin, jotta Frends tietää, mikä prosessi pitää käynnistää, kun jotain rajapinnan päätepisteistä kutsuttaisin. Prosessien linkittämi- sen voi tehdä kahdella tavalla, joko suoraan valikosta (kuva 26) tai kopioimalla valmiiksi linkitetyn prosessin käynnistin toiseen prosessiin ja poistamalla vanhan prosessin linkitys kuvan 26 mukaisen valikon kautta.
43
Koska rajapinnalle ei ollut aiempia toteutuksia, valittiin ensimmäinen vaihtoehto, eli ku- van 26 mukaisesta valikosta valittiin ”Create new linked process”, jolloin Frends luo pro- sessista pohjan, johon on liitetty oikeanlainen käynnistin ja rajapintakuvauksen mukaiset lopetuselementit.
Kuva 26 Prosessin linkitys oikeaan päätepisteeseen
Kuvassa 27 on esitelty Frendsin UI, jossa näkyy prosessin pohja, joka syntyi edellisestä vaiheesta. Mukana on oikeanlainen API/http-käynnistin, jonka kautta kutsut saapuvat prosessille. Lisäksi kuvassa näkyy myös päätepisteet, jotka kuvaavat toteutettavan raja- pinnan eri vastauksia.
Throw-tyyppinen lopetusmuoto, eli kaksi sisäkkäistä ympyrää, joissa on kolmio keskellä, kuvaavat mahdollisia eri virhetilanteita. Jos prosessin suoritus päätyy johonkin näistä, eli suorituksessa tapahtuu virhetilanne, palautetaan rajapinnan kutsujalle elementtiin liitetty virhesanoma sekä määritelty http-statuskoodi. Virhe tulisi myös näkymään Frendsin lo- kissa.
Ympyrä, jonka sisällä ei ole mitään, kuvaa onnistunutta suoritusta ja onnistuneen suori- tuksen tapauksessa kutsujalle palautetaan myös http-statuskoodi, joka onnistuneessa
suorituksessa on 200, sekä rajapintakuvauksen mukainen sanoma, joka POST-metodia käytettäessä on GUID, jonka avulla luotua diagrammia pystyi myöhemmin hakemaan.
Kuva 27 Frendsin luoma prosessipohja
Frendsin luoman alustavan prosessin päälle alettiin kasaamaan itse prosessia. Ensim- mäisenä tehtävänä olisi lisätä prosessiin validointitehtävä, joka validoisi sisään tulevan sanoman.
Tehtävien lisääminen tapahtui valitsemalla sopiva elementti kuvan 27 vasemmassa lai- dassa esiintyvästä työkalupaletista. Tehtävän symboli on suorakaide, jossa on pyöriste- tyt kulmat. Kun symbolin valitsee hiirellä ja siirtää piirtoalustalle, aukeaa kuvan 28 mu- kainen valikko. Valikosta on mahdollista valita, minkä tyyppinen tehtävä halutaan ottaa käyttöön.
45
Kuva 28 Tehtävän lisäys piirtoalustalle sekä muutama valittava Frends-tehtävä
Validointiin käytettävä tehtävä oli yllättäen nimeltään Validate. Tehtävä ottaa paramet- reinä sisään tulevan sanoman, sekä JSON-skeeman, jota vasten sanoma tultaisiin, vali- doi maan (kuva 29).
Kuva 29 Frendsin Validate-tehtävä
Frendissä on ominaisuus, joka muokkaa API-käynnistimen kautta sisään tulevan sano- man sellaiseen muotoon, että sitä pystyy käsittelemään helposti prosessin sisällä ja sa- noman eri osiin voi viitata suoraan pistenotaatiolla samaan tapaan kuin esimerkiksi C#-
kielessä objektin ominaisuuksiin. Eli kun sanoma tulisi käynnistimen läpi, voisi sanoma eri osiin viitata komentamalla ”#trigger.data.body.kentän_nimi”. Sama keino toimisi myös headereihin, polussa annettuihin parametreihin sekä query-parametreihin.
Validointia varten täytyi sisään tulevasta sanomasta luoda JSON-skeema, jota vastaan sanoma tultaisiin validoimaan. Skeema kertoo validaattorille, minkälainen sisään tulevan sanoman tulisi olla ja mitkä kentät sanomassa ovat pakollisia.
Koska kenttiä oli vähän ja sanoman rakenne yksinkertainen, ei skeeman luonti ollut eri- tyisen hankalaa. Sanoman validoinnissa tarkistetiin, että yearFrom- ja yearTo-kentätä olisivat tietyn lukualueen välissä ja että maakoodi valittaisiin kahden enum-tyyppisen merkkijonon väliltä (esimerkkikoodi 1).
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": ["FIN", "SWE"]
},
"yearFrom": {
"type": "number",
"minimum": 1960,
"maximum": 2000 },
"yearTo": {
"type": "number",
"minimum": 1960,
"maximum": 2000 }
},
"required": [
"country",
"yearFrom",
"yearTo"
] }
Sanoman validointiin käytetty JSON-skeema.
Jos sisään tuleva sanoma ei vastaisi luotua JSON-skeemaa, tulisi kutsujalle palauttaa statuskoodi 400 ja virhesanoma, jonka viestissä olisi teksti ”bad request”.
47
Validointitehtävän suorituksen jälkeen, tehtävä palauttaa objektin, joka sisältää boolean- tyyppisen muuttujan, joka kertoo, onnistuiko validointi, sekä string-tyyppisen muuttujan, johon on koottu validoinnissa havaitut puutteet sanoman sisällössä.
Validointitehtävän jälkeen prosessin täytyi vielä lisätä X-Request-ID-headerin talteenotto sekä luoda GUID tiedoston tallennusta varten, ennen kun validoinnin tulosta voitiin tar- kastella.
Koska X-Request-ID-headeria käytettäisiin kutsujen seurantaan, sekä se palautettaisiin kutsujalle onnistuneen tai epäonnistuneen rajapintakutsun tapahtuessa, tulisi header ot- taa talteen.
Talteenoton yhteydessä päädyttiin ratkaisuun, jossa X-Request-ID luotaisiin proses- sissa, jos kutsuja ei sellaista antanut. Samalla muuttuja, johon header tallennettaisiin, käyttäisi niin sanottua promote-ominaisuutta, eli arvo nostettaisiin näkymään Frendsin suorituslokissa, jolloin kutsuja olisi helpompi seurata.
Headerin talteenotto tapahtuisi Expression-tyyppisessä elementissä, jonka symboli löy- tyy kuvan 27 työkalupaletin vasemmasta alalaidasta, heti tehtäväelementin alapuolelta.
Expression-elementtiin on mahdollista lisätä lyhyitä, usein yhden rivin mittaisia C#-koo- dipätkiä. Elementtiä voi käyttää myös muuttujana, johon voi tallentaa esimerkiksi tehtä- vien tai aliprosessien paluuarvoja.
Kuvassa 30 on esitelty X-Request-ID-headerin talteenotto. Käytännössä koodissa tar- kistetaan ainoastaan, että header on mukana käynnistimen kautta tulleessa pyynnössä, ja jos näin ei ole, luodaan uusi GUID.
GUID:n luonti tiedoston tallennusta varten tapahtui lähes samalla tavalla, eli piirtoalus- talle lisättiin uusi elementti, jonka sisään lisättiin kuvassa 30 näkyvän koodin loppuosa, eli pelkkä GUID:n luonti.
Kuva 30 Expression-elementti ja X-Request-Headerin talteenotto
Kun headerin talteenotto ja GUID:n luonti oli toteutettu, voitiin palata jälleen sanoman validoinnin pariin.
BPMN-notaatiossa on elementti nimeltä exclusive decision, joka käytännössä vastaa oh- jelmointikielen if-lausetta. Elementillä ohjataan prosessin kulkua ja mahdollisia haarau- tumisia. Koska validoinnin lopputuloksen perusteella päätettäisiin, jatketaanko prosessin suoritusta vai lopetetaanko suoritus, täytyi tässä kohtaa toteuttaa haarautuminen.
Kuvassa 31 on esitetty exclusive decisionin symboli, sekä ehto, jonka mukaan prosessin suoritus etenee. Yksinkertaisuudessaan prosessin suorituksen saapuessa haarautumi- sen kohdalle tarkastetaan validointitehtävän lopputulos. Jos sanoma oli validi, jatketaan suoritusta yes-haaran suuntaan, ja jos sanoma taas ei ollut validi, mennään alaspäin no- haaran suuntaan.
49
Kuva 31 Exclusive decision ja haarautumisehto
Jos sanoman sisältö ei vastannut aiemmin määriteltyä JSON-skeemaa, eli validointi epä- onnistui, täytyisi rajapinnan kutsujalle lähettää virhesanoma ja vastata oikealla http-sta- tuskoodilla.
Tämän pystyisi toteuttamaan throw-elementillä, joka nimensä mukaisesti heittää virheen.
Frendsissä on käytössä kolme erityyppistä throw-elementtiä, eli expression, http-res- ponse ja binary-http-response. Expression-tyyppinen throw ottaa parametreinä vastaan joko jonkin C#-lauseen tai esimerkiksi pelkää tekstimuotoista dataa. Kun tämäntyyppistä throw-elementtiä käytetään, näkyy virhe ainoastaan Frendsin suorituslokissa.
Kaksi viimeistä throw-elementtiä on suunniteltu rajapintakutsuja varten, ja kuten nimestä voi päätellä, ensimmäinen palauttaa tavallisen http-paluusanoman ja jälkimmäinen bi- näärimuotoisen paluusanoman.
Tässä rajapintatoteutuksessa ei tarvinnut palauttaa suoraan binääridataa, joten tavalli- nen http-paluusanoma oli riittävä.
Kuvassa 32 on esitelty throw-elementin parametrit, eli käytännössä statuskoodi, sanoma ja headerit, jotka palautetaan rajapinnan kutsujalle virheen sattuessa.
Kuva 32 Throw-elementti ja parametrit
Seuraavaksi toteutettiin aliprosessi WebserviceX-kutsua varten, jolloin pääprosessia saatiin hieman lyhyemmäksi. Ajatuksena oli myös, että samaa aliprosessia voisi hyödyn- tää myös muissa toteutuksessa.
Aliprosessin toteutus tapahtuu käytännössä samalla tavalla kuin pääprosessin, eli työ- kalupaletista valitaan elementit ja lisätään ne piirtoalustalle ja tallennettaan prosessi.
Erona on oikeastaan, että prosessit toteutetaan subprocesses-välilehden alle (kuva 33)
51
ja että aliprosessilla ei voi olla kuin manuaalinen käynnistin, eli aliprosessia ei voi käyn- nistää suoraan kutsumalla esimerkkisi jotain http-päätepistettä vaan aliprosessin suori- tus käynnistetään pääprosessista.
Kuva 33 Frends UI:n välilehdet
Käynnistyksen yhteydessä aliprosessille on mahdollista antaa parametrejä, joita voi hyö- dyntää aliprosessin suorituksen aikana (kuva 34).
Koska toteutuksen aliprosessista haluttiin mahdollisimman yleiskäyttöinen, eli että sa- maa prosessia voitaisiin hyödyntää muissa mahdollisissa saman WebserviceX-rajapin- nan kutsuissa, lisättiin aliprosessin käynnistimen parametreihin päätepisteen, kysely ja X-Request-ID-header.
Kuva 34 Aliprosessikutsun parametrit
Päätepiste- ja kyselyparametrin lisääminen mahdollisti sen, että myöhemmässä vai- heessa WebserviceX-rajapintakutsu pystyttiin rakentamaan yhdistelemällä paramet- reinä saatavia arvoja.
Aliprosessin toteutus koostui hyvin pienestä määrää elementtejä (kuva 35) ja verrattuna aloitettuun pääprosessin toteutukseen ainoana uutena asiana olivat scope-elementit, joilla toteutettiin aliprosessiin yksinkertainen virheenkäsittely.
