REST-lukurajapinta

Kuinka REST-lukurajapintaa pääsee käyttämään?

Kukin tiedonkeruuseen osallistuva organisaatio voi hakea tietoja Virta-julkaisutietopalvelun REST-rajapinnan kautta. Rajapintaa pääsee käyttämään ilmoittamalla teknisen yhteyshenkilön yhteystiedot (nimi, organisaatio, sähköposti ja puhelin) ja IP-osoitteen, josta rajapintaa haluaa käyttää sähköpostiosoitteeseen virta-julkaisutietopalvelu@csc.fi

Muut kuin tiedonkeruuseen osallistuvat organisaatiot voivat hakea tietoja tutkimustietovarannon erillislaissa (1238/2021) kuvatun mukaisesti.

Ennen tutkimustietovarannon erillislain voimaantuloa rajapinnan käyttöoikeutta oli laajennettu koskemaan muita kuin tiedonkeruuseen osallistuvia organisaatioita erikseen sovittuja tarkoituksia varten erillisillä tiedonluovutustoimeksiannoilla. Voimassaolevat tiedonluovutustoimeksiannot ovat nähtävillä wikisivulla: Tiedonluovutustoimeksiannot

Rajapinta tarjoaa työkalut julkaisujen etsimiseen eri hakukriteerien perusteella, sekä yksittäisen että useamman julkaisun hakemiseen. Julkaisut ovat saatavilla sekä JSON- että XML-muodossa (Julkaisu-XML).

Huomaathan että tietoja lukevan organisaation käyttämän Curl:in versio vaikuttaa sille annettujen parametrien toimintaan.

Lisätietoja ja ohjeita rajapinnan käytöstä saa osoitteesta: virta-julkaisutietopalvelu@csc.fi

Haku

/julkaisut/haku
/julkaisu/haku/xml

Hakutulokset palauttavat JSON-muodossa suppeamman tietojoukon,  jossa on vain osa julkaisujen perustiedoista. Hakutulokset saa myös XML-muodossa, jolloin palautuvat kaikki tiedot. Katso hakuesimerkit ohjeen loppupuolelta.

JSON-muodossa palautettavat tiedot:

"julkaisunTunnus" ,"julkaisunNimi","tekijat","julkaisuVuosi","julkaisuTyyppi","lehdenNimi","issn","muutospvm","luontipvm","julkaisunTila,"julkaisunOrgTunnus", "jufoTunnus", "organisaatioTunnus" ja "ilmoitusVuosi"

XML-muodossa palautettavat tiedot:

Katso Julkaisut-XML skeeman määrittelytiedot ja kuvaukset.

Hakuparametrit

Hakuesimerkkejä

Useamman julkaisun tieojen hakeminen. Haetaan lehden nimen ja organisaatiotunnuksen mukaan (XML ja JSON (julkaisusjen perustiedot)).

Esimerkissä lehtenä on Suomen lääkärilehti nimi URL enkoodattuna.

# curl  -k -i -H "Accept: application/xml" https://virta-jtp.csc.fi/api/julkaisut/haku/xml?lehdenNimi=Suomen%20L%C3%A4%C3%A4k%C3%A4rilehti&organisaatioTunnus=01901

# curl  -k -i -H "Accept: application/json" https://virta-jtp.csc.fi/api/julkaisut/haku?lehdenNimi=Suomen%20L%C3%A4%C3%A4k%C3%A4rilehti&organisaatioTunnus=01901

Haettavien julkaisujen rajaaminen julkaisutyypin perusteella. Muut hakuehdot: Lehti: ”Suomen Lääkärilehti” ja Organisaatio on 01901

# curl  -k -i -H "Accept: application/json" https://virta-jtp.csc.fi/api/julkaisut/haku?lehdenNimi=Suomen%20L%C3%A4%C3%A4k%C3%A4rilehti&julkaisuTyyppi=A1

# curl  -k -i -H "Accept: application/json" https://virta-jtp.csc.fi/api/julkaisut/haku?julkaisuVuosi=2014&organisaatioTunnus=01901

Yksittäisen julkaisun tietojen hakeminen

/julkaisut
/julkaisut/xml

Yksittäisen julkaisun hakeminen rajapinnasta XML ja JSON muodossa tapahtuu JulkaisunTunnus arvon perusteella. Kyseessä on Julkaisun yksiselitteisesti identifioiva koodi. Samalla julkaisulla ei voi olla olemassa useampaa julkaisuntunnusta. Julkaisuntunnuksia voi etsiä yllä olevan hakutoiminnallisuuden perusteella.

Hakuesimerkkejä

# curl -k -i -H "Accept: application/xml" https://virta-jtp.csc.fi/api/julkaisut/xml/000051414

# curl -k -i -H "Accept: application/json" https://virta-jtp.csc.fi/api/julkaisut/000051414

Rajoitetun pääsyn rajapinnat

Julkaisutiedonkeruun rajapinta sisältää myös muita rajapintoja mutta ne on tarkoitettu vain nimettyä käyttötarkoitusta varten ja niihin pääsyä on rajoitettu. Kyseiset rajapinnat sisältävät toiminnallisuuksia esimerkiksi tietojen syöttämistä varten tai sisältävät historiatietoa esimerkiksi tilastollisia tarkoituksia varten.

Näitä rajapintoja ovat mm:

/julkaisut/{julkaisunTunnus}/hanke
/julkaisut/{julkaisunTunnus}/juuli
/TKjulkaisut

Esimerkkivastauksia

Yksittäisen julkaisun tiedot XML-muodossa: 0010696814.xml

Yksittäisen julkaisun tiedot JSON-muodossa:0010696814.json

Hakutulokset JSON-muodossa:haku.json