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ä versio 2.
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) tai GraphQL(ulkoinen linkki):n 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 alla. Arvot löytyvät myös rajapintojen teknisessä dokumentaatiosta.
Katso myös havainnollistava diaesitys: Harvennusmallien siirto omaan tietojärjestelmään, 2024 (pdf)(ulkoinen linkki)
Harvennusmallihaun parametrit ja parametriarvot:
forestInformationStandard:
Metsätietostandardin koodeille tarkoitettu parametri. Harvennusmallihaussa käytettävät metsätietostandardin mahdolliset koodistot ja koodit on lueteltu Rajapintaoppaan Metsätietostandardi-osassa.
Parametriin voi lisätä yhden tai useamman eri koodiston yhtä aikaa. Huom. annetut arvot toimivat AND-periaatteella, eli jos annetaan kaksi ristiriitaista, eri tulokseen johtavaa parametria, niin lopputuloksena on tyhjä tulos.
forestActAreaType:
Metsälakialue.
- Northern_Finland: Pohjoinen Suomi
- Central_Finland: Keskinen Suomi
- Southern_Finland: Eteläinen Suomi
mainTreeSpecies
Pääpuulaji.
- pine: Mänty
- spruce: Kuusi
- silver_birch: Rauduskoivu
- downy_birch: Hieskoivu
fertilityClassType
Kasvupaikkaluokka.
- Site_2: Lehtomainen kangas tai vastaava turvekangas
- Site_3: Tuore kangas tai vastaava turvekangas
- Site_4: Kuivahko kangas tai vastaava turvekangas
- Site_5: Kuiva kangas tai vastaava turvekangas
soilType
Maalaji.
- Mineral_soil: Kivennäismaa
- Organic_soil: Turvemaa
npv
Korko.
- NPV_15: 1,5 % korko
- NPV_30: 3 % korko
- NPV_50: 5 % korko
modelType
Harvennusmallien mallityyppi.
- thin_from_below: Alaharvennus (oletus)
- thin_from_above: Yläharvennus
- mixed_species: Sekapuuston malli
- extended_rotation: Pidennetty kiertoaika
mixedSpeciesModel
Sekapuuston puulajisekoitus.
- pine_and_mixed_broadleaves: Mänty-koivusekametsä
- spruce_and_mixed_broadleaves: Kuusi-koivusekametsä
- spruce_and_mixed_pine: Kuusi-mäntysekametsä
xAxis
Puuston pituuden muuttuja.
- hdom: Valtapituus
- hmean: Keskipituus
yAxis
Puuston tiheyden muuttuja.
- BA: Pohjapinta-ala
- tnum: Runkoluku
Metsätietostandardien hyödyntäminen haussa
Toimenpiteiden kuvauksia ja toteutuksia sekä harvennusmalleja on mahdollista hakea rajapinnasta metsätietostandardin koodin avulla. Toimenpiteiden kuvauksien ja toteutuksien osalta REST-rajapinnassa on tätä varten erillinen rajapintapäätepiste haulle (esim. /v2/operation-descriptions/search) ja GraphQL-rajapintaan on toteutettu hakukysely (esim. OperationDescriptionSearch()).
Sekä 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ä(ulkoinen linkki) "OperationDescriptionSearch"-nimisestä esimerkkikyselystä. Esimerkkikyselyn muuttujissa on valmiina täytettynä taimikonharvennuksen työlajikoodi.
Harvennusmallihaku rajapinnassa
Harvennusmallien haku metsätietostandardin koodeilla on samassa ei-standardin mukaisten parametrien kanssa. REST-rajapinnassa on harvennusmallihaulle rajapintapäätepiste (/v2/v2/thinning-models/search) ja GraphQL-rajapinnassa haku toteutetaan kyselyllä ThinningModelSearch(). Molemmissa rajapinnoissa harvennusmalleja vain osan mallien parametreista voi kuvata metsätietostandardin koodeilla. Käytössä olevat koodistot ja koodit on kuvattu Rajapintaoppaan osiossa Metsätietostandardi.
Malleja voi hakea yhdistämällä sekä sisäisiä parametreja että metsätietostandardin koodeja. Huomiota kuitenkin pitää kiinnittää, että ei käytä kuvaamaan yhtä mallin parametria yhtä aikaa metsätietostandardin koodia sekä harvennusmallien sisäisiä parametreja. Esimerkiksi harvennusmallien kasvupaikkaluokka tuore kangas voidaan kuvata sisäisellä parametrilla "site_3" tai metsätietostandardin koodiston FertilityClass koodilla 3. Harvennusmallihaku toimii aina rajaavasti (AND) eli jos annetaan kaksi ristiriitaista, eri tulokseen johtavaa parametria, niin lopputuloksena on tyhjä tulos.
Esimerkki harvennusmallin hakemisesta metsätietostandardin koodeilla GraphQL-rajapinnasta löytyy GraphQL-selaimen aloitusnäkymästä(ulkoinen linkki) "ThinningModelSearch"-nimisestä kyselystä. Harvennusmallien haun osalta GraphQL-rajapintaan pätee samat parametrien käyttöön liittyvät periaatteet kuin REST-rajapintaan.