Tekniset ohjeet sivu kuvaa rajapintapalvelun hakutoimintoja teknisestä näkökulmasta. Rajapintapalvelu pitää sisällään ison joukon päätepisteitä (REST API endpoint) sekä GraphQL(ulkoinen linkki) kyselyrajapinnan. Tässä ohjeistuksessa kuvataan teknologioiden eroja ja pyritään selventämään milloin on tarkoituksenmukaista valita REST ja milloin GraphQL rajapinta. Lisäksi ohjeessa kuvataan hakujen periaatteita ja esimerkinomaisesti osa päätepisteistä.
Tarkemmat tekniset yksityiskohdat jokaisen erillisen REST päätepisteen sekä GraphQL rajapinnan osalta löytyvät api.metsanhoidonsuositukset.fi(ulkoinen linkki) palvelusta. Lisäksi on katsottavissa videoesittely(ulkoinen linkki), jossa esitellään rajapintojen tärkeimmät tekniset yksityiskohdat ja hakutoiminnoista.
Hakutoiminnot
Metsänhoidon suositukset -järjestelmästä voi siirtää metsänhoidon suositusten ajantasaista sisältöä ulkopuolisiin tietojärjestelmiin, sovelluksiin ja verkkosivustoille avoimen rajapinnan kautta. Metsänhoidon suositusten kaikki tiedot ovat käytettävissä täysin avoimesti ilman autentikointia. Käytössä tietojen hakemiseen on kaksi eri teknologiaa: GraphQL API ja REST API. Molemmat toimivat HTTP:n yli lähettämällä HTTP-pyynnön ja vastaanottamalla vastauksen.
Rajapinnoista on tällä hetkellä käytössä kaksi versiota, versio 1.x ja 2.x. Versio 1 toimii edelleen mutta sitä ei enää kehitetä. Kaikki uudet toiminnallisuudet toteutetaan versio 2:een.
REST pääpiirteissään:
- Rajapintakutsut tehdään ennalta määritettyihin rajapintapäätepisteisiin (kts. Swagger)
- Kullekin tietotyypille on varattu oma päätepiste
- Kunkin päätepisteen tuottama vastaus on vakiomuotoinen
GraphQL pääpiirteissään:
- Rajapintakutsu tehdään aina samaan päätepisteeseen
- Kutsu sisältää rajapintakyselyn – kullekin tietotyypille on määritelty oma kyselytyyppi – tämä vastaa suurin piirtein samaa kuin REST-rajapinnan tietotyyppikohtaiset päätepisteet
- Rajapinnan käyttäjä voi määrittää, mitkä tietotyypin tiedot rajapintavastaus palauttaa
Yhteen kyselyyn voidaan sisällyttää useita tietotyyppejä tietorakenteen hierarkian sallimissa rajoissa – kts. kyselyesimerkki “OperationDescriptionByCode” – toimenpiteen kuvauksen hakeminen työlajikoodilla GraphQL Explorer -dokumentaatiotyökalussa(ulkoinen linkki).
Kumpaa teknologiaa tulisi käyttää?
Rajapinnan käyttäjän tulee arvioida teknologian valinta itse. Molemmissa teknologioissa on etunsa. Periaatteellinen ero näiden kahden välillä on se, että REST-vastaukset voivat sisältää paljon tai vastaavasti liian vähän dataa, mikä luo tarpeen uusille pyynnölle, kun taas GraphQL mahdollistaa hakujen tarkemman rajaamisen ja toisaalta niiden laajentamisen. GraphQL:n suurin etu onkin sen kyky käyttää mitä tahansa tietoa tai kaikkia tietovaraston tietoja yhden API-päätepisteen kautta. Lisäksi GraphQL on hyvin kehittäjäystävällinen, sillä rajapintavastauksissa mm. palautetaan yleensä hyvin tarkat virhetiedot, mikäli käyttäjä on muotoillut rajapintakutsun väärin. REST rajapinnalla on omat vahvuutensa, joista yksi tärkeimmistä on sen oppimisen helppous sekä käytön suoraviivaisuus. Molemmilla teknologioilla pystytään hakemaan samat tiedot.
Harvennusmallit
Harvennusmalleja voi hakea REST-rajapintapisteen(ulkoinen linkki) kautta. Harvennusmallien hakukriteereinä voi osin käyttää metsätietostandardikoodeja ja lisäksi hakuparametreja voi määrittää harvennusmalleihin tallennetun metadatan avulla. Metadata määritetään rajapintakutsussa parametreina, ja parametrien mahdolliset arvot on lueteltu REST-rajapinnan teknisessä dokumentaatiossa(ulkoinen linkki).
GraphQL-kysely harvennusmalleille on tulossa GraphQL-rajapintaan myöhemmin.
Metsätietostandardien hyödyntäminen haussa
Toimenpiteiden kuvauksia ja toteutuksia on mahdollista hakea rajapinnasta metsätietostandardin koodin avulla. REST-rajapinnassa on tätä varten erillinen rajapintapäätepiste haulle (esim. /v2/operation-descriptions/search) ja GraphQL-rajapintaan on toteutettu hakukysely (esim. OperationDescriptionSearch()).
REST-rajapinnan dokumentaatiossa on esimerkkikutsu toimenpiteen hakemisesta metsätietostandardikoodilla(ulkoinen linkki). Aktivoi dokumentaationtyökalun kokeilutila ensin painamalla “Try it out” -painiketta, ja tämän jälkeen voit suorittaa rajapintakutsun painamalla “Execute”-painiketta. Esimerkin kentässä on valmiiksi täytettynä taimikonharvennuksen työlajikoodi. “Execute”-painikkeen painamisen jälkeen dokumentaatiotyökalu näyttää rajapintakutsun curl-komennon sekä URL-osoitteen, ja näiden alle tulee rajapinnan vastaus JSON-muodossa.
Esimerkki metsätietostandardin koodilla hakemisesta GraphQL-rajapinnasta löytyy GraphQL-selaimen aloitusnäkymästä "OperationDescriptionSearch"-nimisestä kyselystä(ulkoinen linkki).