Finto tarjoaa avoimen REST-tyyppisen rajapinnan, joka mahdollistaa sanastotoiminnallisuuksien integroinnin omiin sovelluksiin. Tässä ohjeessa käydään läpi esimerkkien avulla Finton sanastojen käyttöä kuvitteellisessa kuvailujärjestelmässä. Tämän ohjeen ohella kannattaa tutustua rajapinnan tekniseen dokumentaatioon GitHubissa.

Finton sanastot on mahdollista ottaa käyttöön kahdella tavalla: tekemällä yksittäisiä hakuja rajapinnan kautta tai ottamalla sanastosta paikallinen kopio omaa järjestelmää varten.

Rajapinnan kautta käytettynä sanastot ovat aina ajantasaisia. Paikallinen kopio taas on syytä päivittää esimerkiksi kerran kuukaudessa. Toki on myös mahdollista että rajapinnan kautta haettuihin käsitteisiin tulee muutoksia, joten kuvailutietueissa olevat viitteet sanastojen käsitteisiin on hyvä ajoittain tarkistaa automaattisesti.

Esimerkki Fintoa hyödyntävästä kuvailujärjestelmästä

Esimerkissämme kuvailija käyttää YSOa suomen kielellä kuvaillessaan äänitallennetta. Käyttäjä hakee YSOsta käsitettä hakusanalla kissa ja saa nähdäkseen listan käsitteitä joiden termeihin hakuehto on osunut. Hän valitsee sen jälkeen listalta sopivimman käsitteen, joka tässä tapauksessa on kissaeläimet. Tässä vaiheessa järjestelmän on syytä ottaa talteen käsitteen päätermi (skos:prefLabel) kaikilla kolmella YSOn tukemalla kielellä. Termien lisäksi kuvailutietueeseen on tärkeää tallentaa myös käsitteen URI (yksilöllinen tunniste). Tämän tunnisteen avulla käsitteen tiedot voidaan myöhemmin tarkistaa mahdollisten muutosten varalta.

Toteutus Finto-rajapinnan kautta:

Käyttäjän syötettyä hakusanan hakulaatikkoon tehdään rajapinnan search-metodiin kutsu:

http://api.finto.fi/rest/v1/yso/search?query=kissa*&lang=fi&fields=prefLabel

Jonka vastauksista näytetään hänelle lista mahdollisista käsitteistä. Kyselyn lopussa oleva parametri fields arvoineen prefLabel kertoo rajapinnalle että olemme kiinnostuneet käytettävistä termeistä myös muilla kielillä kuin hakukielellämme (suomi). Fields-parametrin avulla voi hakea myös muita skos-ominaisuuksia. Esimerkiksi jos hakutuloksissa halutaan näyttää jokaisen käsitteen yläkäsite, lisätään fields-parametriksi myös broader:

http://api.finto.fi/rest/v1/yso/search?query=kissa*&lang=fi&fields=prefLabel+broader

 

Kun käyttäjä valitsee listasta käsitteen kissaeläimet tallennetaan käsitteen tiedoista järjestelmään vähintään URI sekä prefLabelit eli käytettävät termit eri kielillä. Nämä tiedot talletetaan myös kuvailtavaan tietueeseen siten, että kuvailun kohde on mahdollista löytää riippumatta siitä minkä kieliseen termiin tiedonhakijan termihaku kohdistuu. Tämän lisäksi voidaan tehdä haluttaessa kaikki käsitteen tiedot noutava kutsu rajapinnan data-metodille. Tämä on hyödyllinen jos koko käsite halutaan tallettaa järjestelmään, tai tarvitaan ominaisuuksia jotka eivät ole SKOSin mukaisia joten niitä ei voi kysyä suoraan fields-parametrin kautta.

http://api.finto.fi/rest/v1/yso/data?uri=http://www.yso.fi/onto/yso/p864

Tämän kutsun vastauksesta poimitaan järjestelmästän tarpeista riippuen sopivat kentät.

Voit rajoittaa rajapinnan palauttamat käsitteet esimerkiksi skos:Concepteihin (tavalliset käsitteet), jolloin saat vain kuvailussa sallitut käsitteet etkä esimerkiksi käsiteryhmiä.

http://api.finto.fi/rest/v1/yso/search?query=*filosofia&lang=fi&type=skos:Concept

Toteutus tuomalla koko sanasto ohjelmistoon:

Vaiheet ovat käytännössä identtiset, mutta vastuu sanastotiedon hyödyntämisestä on järjestelmän kehittäjällä. Järjestelmän tulee mielellään lukea termit suoraan RDF-datasta, mutta vähintään talteen on otettava URIt, käsitteen käytettävät termit (prefLabelit) eri kielillä ja mahdollisesti myös ohjaustermit (altLabelit). Nämä on talletettava järjestelmässä siten, että mahdolliset muutokset termeihin tai muihin käsitteen ominaisuuksiin voidaan päivittää helposti. Huomioitavaa on myös, että mahdolliset muutokset käsitteiden termeihin on vietävä myös järjestelmän kuvailutietoihin.

Finton sanastojen etusivuilla (tässä YSO) on alalaidassa latauslinkit joista koko sanaston voi ladata joko RDF/XML tai TURTLE -serialisoituna. Näiden käsittelyyn kannattaa käyttää jotain valmista RDF-kirjastoa. Esimerkkeinä mainittakoon käyttämämme kirjastot: EasyRdf PHPlle, RDFLib Pythonille ja Apache Jena Javalle.

Toteutuksessa huomioitavat erityistapaukset

Joissakin tilanteissa käsite voidaan korvata toisella käsitteellä. Korvatut käsitteet eivät näy hakutuloksissa, mutta kuvailutietueisiin niitä on saattanut jäädä ajalta ennen deprekointia. Näin on käynyt esimerkiksi YSOn (Yleinen suomalainen ontologia) käsitteelle tunteminen joka on korvatttu käsitteellä tunteet. Rajapinnassa tämä voidaan huomata ominaisuudesta (owl:deprecated true), käsitteen tyypistä (rdf:type skosext:DeprecatedConcept) ja suhteesta (yso:p307 dc:isReplacedBy p3485). Kun järjestelmä huomaa käytetyn käsitteen deprekoidun, tulee sen vaihtaa kuvailutietuiden tunteminen-käsitteen viittaukset tunteet-käsitteeseen.

http://api.finto.fi/rest/v1/yso/data?uri=http://www.yso.fi/onto/yso/p307

Hakuesimerkki Fintoa hyödyntävästä järjestelmästä

Jatkamme edellisen esimerkin järjestelmän käyttöä. Nyt kuitenkin vuorossa on tiedonhakija joka etsii järjestelmästä aineistoa. Käyttäjä tekee järjestelmään haun: kattdjur. Vaikka järjestelmän kuvailutieto syötettiin edellisessä esimerkissä suomen kielellä, on teos kuitenkin löydettävillä myös ruotsinkielisellä termillä YSOn kolmikielisyyden ansiosta.