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 otlai-taa joitain vapauksia, eikä noudatlai-taa 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ä diadia-grammi 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 sovellukmahdolli-seen. 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 kutkut-sujalle 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).
{
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-boolean-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-reshttp-res-ponse. 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ä
Päätepiste- ja kyselyparametrin lisääminen mahdollisti sen, että myöhemmässä