Ratkaistaan: Lähtölaukaus verkkorajapintojen kehitykseen

24.1.2023Jani Nevaranta, Full-stack -kehittäjäRatkaistaan

Web APIt eli verkkorajapinnat ovat olennainen osa tietopohjaisen arkkitehtuurin rakentamista. Rajapintojen avulla tietoa voidaan siirtää mutkattomasti järjestelmästä ja ympäristöstä toiseen hyödyntäen verkossa tapahtuvaa tiedon liikkumista. Kuinka verkkorajapinta sitten rakentuu? Nimensä mukaisesti tässä Ratkaistaan-artikkelissa teemme pienimuotoisen lähtölaukauksen verkkorajapintakehitykseen ja käymme läpi muutamia ensivaiheita liittyen verkkorajapintojen kehittämiseen.

Kuvituskuva. Tusseilla piirretty kuva jossa hahmotemia erilaisista datan näkymistavoista.
Lähde: Hal Gatewood, Unsplash.com.

Ennen niin sanotusti käsien saveen pistämistä meidän täytyy määritellä verkkorajapinnan tarpeet ja käyttötarkoitus. Lähdetään ensin purkamaan sitä, minkälaista dataa esimerkkirajapintamme tulee palvelemaan.

Kuvitellaan, että olemme asentaneet kävijälaskureita hiljaiselle ulkoilukohteelle maakunnassa. Laskurit laskevat niiden ohi kulkevan henkilön ja tallettavat kellonajan milloin laskuri ohi kuljettiin. Kukin laskuri pystyy lähettämään tallennetut henkilömäärät kellonaikoineen palvelimelle tasaisin väliajoin. Haluamme käyttää kävijälaskureiden mittaustuloksia erilaisten analyysien tekemiseen, jonka vuoksi tarvitsemme verkkorajapinnan tiedon reaaliaikaiselle välittämiselle.

Ensisilmäyksellä voisi vaikuttaa, että tehtävästä tulisi erittäin simppeli – tallennetaan laskureiden lähettämät määrät tietokantaan, josta sitten käyttäjä voi rajapinnan avulla poimia kunkin päivän kävijät. Pienellä lisävaivalla voimme kuitenkin helpottaa analysoinnin päässä tapahtuvaa tiedon siivoamista ja koota tietoa jo näppärästi rajapinnan päässä. Rajapinnan käyttäjä voisi siis saada jo valmiiksi kootusti dataa esimerkiksi seuraavilla määritteillä:

  • Yksittäisen päivän kävijät
  • Yksittäisen laskurin kävijät
  • Kuluneen viikon kävijät
  • Ja niin edelleen...

Tällä tavoin kootun tiedon tarjoaminen ja suodattaminen helpottaa huomattavasti rajapinnan käyttäjän tapoja hyödyntää tietoa - käyttäjän ei tarvitse kahlata kutakin päivää erikseen. Loppujen lopuksi haluamme kuitenkin oikean tiedon päätyvän mahdollisen mutkattomasti lopulliseen käyttötarkoitukseen.

Rajapinnan tarpeiden suunnittelun jälkeen voimme lähteä työstämään itse rajapintaa. Ensin meidän pitää valita arkkitehtuurimalli, jonka standardien mukaan haluamme verkkorajapinnan rakentaa. Vaihtoehtoja on pilvin pimein, mutta päädymme valitsemaan tähän tarkoitukseen hyvin yleiseksi muodostuneen RESTful-arkkitehtuurin, joka sopii hyvin numerollisen datan välittämiseen.

Nyt kun olemme kutakuinkin hahmottaneet minkälaista dataa saamme rajapinnasta, missä muodossa se on ja millä standardeilla haluamme sitä jakaa, voimme lähteä miettimään rajapinnan niin sanottuja ”endpointteja” eli päätepisteitä. RESTful-arkkitehtuurissa data tuodaan rajapinnasta ja kerätään käyttäen HTTP-protokollaa URI:en välityksellä. Arkikielisenä voimme puhua, että tuomme ja keräämme datan käyttäen verkko-osoitetta. Määrittelemme siis kullekin datan keruu- ja tuontiosoitteelle oman polkunsa.

Pelkkä verkko-osoite tai -polku ei kuitenkaan riitä, vaan meidän pitää myös määritellä minkälaista HTTP-metodia verkko-osoitepolku käyttää. Metodeita on erilaisia, mutta ne ovat onneksi melko yksiselitteisiä englanninkielisiä nimityksiä. Esimerkkeinä HTTP-metodeista, joita RESTful-rajapinnat tukevat ovat GET, POST ja PUT; GET hakee tietoa, POST muokkaa sitä ja PUT tuo uutta tietoa rajapintaan.

Tunnistettuamme rajapinnan päätepisteiden tarpeet voimme lähteä kokoamaan niitä vaikkapa aikaisemmin esimerkkinä antamille toiminnoille:

  • Yksittäisen päivän kävijät (päivä muodossa päivä-kuukausi-vuosi)
    • /kavijat/paiva/01-01-2022, GET-metodi
  • Yksittäisen laskurin kävijät (kukin laskuri omalla tunnistenumerollaan
    • /kavijat/laskuri/1, GET-metodi
  • Kuluneen viikon kävijät (viikko viikkonumerolla)
    • /kavijat/viikko/3, GET-metodi

Näiden lisäksi voimme määritellä erikseen myös PUT-metodit, jolloin voimme samaa polkua mutta eri metodia käyttäen tuoda uutta dataa rajapintaan. Koska laskurit ovat tällä hetkellä ainoita asioita, jotka uutta dataa rajapintaan tuovat, voimme määritellä /laskuri/ -polulle PUT-metodin laskureiden datan tuomiseksi.

Viimeisenä haluamme vielä päättää millä työkaluilla alamme rajapintaa rakentamaan. Tähän tarkoitukseen meille sopii mainiosti esimerkiksi Python-ohjelmointikielen päälle rakennettu avoimen lähdekoodin FastAPI-ohjelmointikehys, jolla yksinkertaisien rajapintojen kehittäminen on nimensä mukaisesti suhteellisen nopeata ja mutkatonta.

Näin olemme saaneet hyvän, vaikkakin hieman karkean, lähtölaukauksen rajapinnan kehittämiseen. Suunnittelutyötä kannattaa tietysti aina miettiä laajamittaisemmaksi itse ratkaistavan ongelman mukaan, mutta luomallamme viitekehykselle pääsemme mallikkaasti jo työn alkuun. Nyt eikun kädet sinne saveen!

Hyödyllisiä linkkejä rajapintojen kehittämiseen:

Jaa artikkeli

Ratkaistaan

Lue myös