Tietojen haku rest-rajapinnasta

KohderyhmäKunta
AsiakirjatyyppiOhje
Antopäivämäärä09.04.2020
KategoriatTietojen haku ja hyödyntäminen
YlläpitovastuuValtiokonttori

Hyväksytyt ja rekisteripalveluun siirtyneet tiedot ovat saatavilla rest-rajapinnan kautta JSON- ja XML-formaateissa.

Tunnuslukujen haku rest-rajapinnan kautta tapahtuu kaksivaiheisesti.

1. Ensiksi haetaan kaikki palvelusta löytyvät aineistotiedot.

2. Tämän jälkeen tulosjoukon tunnistetiedoilla (y-tunnus, raportointikokonaisuus jne.) voidaan valita haluttu aineisto. Tulosjoukkoon on valmiiksi koostettu Url-osoite, jolla voidaan hakea juuri kyseiseen aineistoon liittyvät tunnusluvut.

Tapa hakea tiedot riippuu luonnollisesti myös tietojen hakuun käytettävästä sovelluksesta/selaimesta.

Rest-rajapinnan osoite

Rest-rajapinta löytyy osoitteesta:
https://prodkuntarest.westeurope.cloudapp.azure.com/.

Mentäessä osoitteeseen aukeaa alla oleva näkymä, jossa on ohjeita rajapinnan käyttöön.

Kuva 1 Rekisteripalvelun Rest-rajapinnan etusivu

Tuotantokäytössä tiedot ovat rajapinnan kautta saatavilla kaikille.

Aineistotietojen haku ja esimerkkihakuja

Aineistotietojen haussa on käytössä seuraavat parametrit:

  • Versio: v1
  • Formaatti: json tai xml (myöhemmin myös xbrl ja jxbrl)
  • Aineistot-avainsana: aineistot, collection, samling

Edellä mainittuihin parametreihin perustuen, kaikki palvelusta löytyvät aineistotiedot voidaan hakea:
https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/<aineistot-avainsana>
. Kulmasulkeilla on merkitty osoitemuodon parametriosat. Kyseisiä merkkejä ei tule käyttää todellisissa osoitteissa.

1. JSON-muodossa:
https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/json/aineistot

2. XML-muodossa:
https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/xml/aineistot.

Alla on esimerkinomaisesti toteutettu sama aineistotietojen haku muutamilla eri sovelluksilla.

Esimerkki 1. JSON-formaatissa olevien aineistotietojen haku Firefox-selaimella.

Mentäessä Firefox -selaimella yllä olevaan osoitteeseen
https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/json/aineistot, avautuu JSON-formaatissa oleva tekstimuotoinen näkymä

Kuva 2 JSON-formaatissa olevien aineistotietojen haku Firefox-selaimella

Firefoxiin on saatavilla myös lisäosia, joilla json-formaatin saa näkymään siistimmin muotoiltuna.

Kuva 3 Json-formaatin näyttäminen siistimmin muotoiltuna

Esimerkki 2. JSON-muotoinen aineistotietojen haku Internet Explorerilla.

IE-selain ehdottaa osoitteesta haettavien aineistotietojen (aineistot.json) avaamista työaseman sovelluksella tai aineistotietojen tallentamista työasemalle.

Kuva 4 JSON-muotoinen aineistotietojen haku Internet Explorerilla, latausikkuna

Haun jälkeen aineistotiedot voidaan avata työaseman sovelluksessa (esim. muistio).

Kuva 5 JSON-muotoinen aineistotietojen haku Internet Explorerilla

Esimerkki 3. JSON-muotoinen aineistotietojen haku SoapUI-sovelluksella.

Aineistotiedot saadaan haettua komennolla:

GET https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/json/aineistot HTTP/1.1.

Kuva 6 JSON-muotoinen aineistotietojen haku SoapUI-sovelluksella

Rajapinnassa on kutsumuodot myös englanniksi ja ruotsiksi:

https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/json/collection

https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/json/samling

Aineistotietojen tulkinta

Aineistotiedoissa on tiedot kaikista rekisteripalvelussa olevista aineistoista sekä kunkin aineiston osalta seuraavat tiedot:

  • Y-tunnus
  • Raportointikokonaisuus
  • Raportointikausi
  • Hyväksyntävaihe
  • Hyväksymisaika
  • Url-osoite tunnuslukuja varten

Tulosjoukon tunnistetiedoilla (y-tunnus, raportointikokonaisuus jne) valitaan haluttu aineisto ja tulosjoukkoon valmiiksi koostetulla Url-osoitteella voidaan hakea kyseiseen aineistoon liittyvät tunnusluvut. Valmiissa tunnuslukujen hakuosoitteissa käytetään samaa siirtomuotoa, jolla haettiin kaikki aineistotkin. Jos kaikki aineistot on pyydetty json-formaatissa, niin ko. aineistolistauksessa olevat Url-osoitteet ovat myös parametroitu json-pohjaisia tunnuslukulistauksia varten. Vieraskielisten aineistojen Url-kutsut viittaavat myös vieraskielisiin tunnuslukukutsuihin. Tunnusluvut hakeva Url-osoite on helppo muodostaa koneellisestikin. Näin joudutaan toimimaan, jos valmiin tunnuslukuhaun parametriarvoja (kuten tarkistustapausten kielisyyttä) halutaan muuttaa.

Edellisessä tulosjoukossa oli vain yksi aineisto, jonka tunnusluvut ovat haettavissa seuraavalla osoitteella:

https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/json/dokumentti/lopullinen/ktas/0186588-2/2019

Kuva 7 Aineistotietojen tulkinta

Yllä tehdystä esimerkkihausta tulee huomata, että esimerkkinä annetut rajapintahaut on toteutettu testiaineistolla, jolloin haut eivät välttämättä palauta samoja tuloksia todellisessa ympäristössä.

Tiettyyn aineistoon kuuluvien tunnuslukujen haku

Aiemmin yllä esitettiin aineistotietojen haku. Aineistotietojen tulosjoukon tunnistetiedoilla (y-tunnus, raportointikokonaisuus jne) voidaan valita haluttu aineisto. Tulosjoukkoon on myös valmiiksi koostettu URL-osoite, jolla voidaan hakea kyseiseen aineistoon liittyvät tunnusluvut.

Valmiissa tunnuslukujen hakuosoitteissa käytetään samaa siirtomuotoa, jolla haettiin kaikki aineistotkin. Jos kaikki aineistot on pyydetty JSON-formaatissa, niin ko. aineistolistauksessa olevat URL-osoitteet on myös parametroitu JSON-pohjaisia tunnuslukulistauksia varten. Tunnusluvut hakeva URL-osoite on helppo muodostaa koneellisestikin. Näin joudutaan toimimaan, jos valmiin tunnuslukuhaun parametriarvoja (kuten tarkistustapausten kielisyyttä) halutaan muuttaa.

Aineistojen tunnuslukujen haussa on käytössä seuraavat parametrit:

  • Versio: v1
  • Formaatti: json, xml (myöhemmin myös xbrl ja jxbrl)
  • Dokumentti-avainsana: dokumentti, document tai dokument
  • Hyväksyntävaihe, suomi: esi, alustava, hyväksytty, lopullinen.
  • Hyväkstyntävaihe, englanti: initial, approved, final.
  • Hyväkssyntävaihe, ruotsi: preliminär, godkänt, slutlig
  • Raportointikokonaisuus: ktas (muita ei tueta tällä hetkellä).
  • Y-tunnus: kunnan tai sen liikelaitoksen Y-tunnus, esimerkiksi 0145208-4.
  • Kausi: 2018, 2019 jne.

Dokumentti-avainsana ja hyväksyntävaihe pitää kirjoittaa samalla kielellä, jotta järjestelmä tunnistaa pyynnön oikein. Esimerkiksi dokumentti ja lopullinendocument ja final tai dokument ja slutlig.

Vaikka tunnuslukuhaku tehdään vieraskielisenä niin tuloksissa kommenttikenttä on vain sillä kielellä millä kommentoija on sen kirjoittanut. Järjestelmä ei käännä kommentteja halutulle kielelle.

Tiettyyn aineistoon kuuluvien tunnuslukujen tulkinta

Tunnuslukuhaun tuloksissa on saatavilla seuraavat tiedot:

  • Y-tunnus
  • Raportointikokonaisuus
  • Raportointikausi
  • Hyväksyntävaihe
  • Hyväksymisaika
  • Taksonomia
  • Tunnusluku (taksonomian mukainen numerokoodi)
  • Tunnusluvun arvo
  • Tarkastustapauksen ilmoitus
  • Tarkastustapauksen tarkennus
  • Tarkastustapauksen vakavuus
  • Tarkastustapauksen kieli

Alla yhden esimerkkihavainnon sisältämät tiedot.

Kuva 8 Esimerkkihavainnon tunnuslukutiedot

Taloustietojen latauksissa on toistaiseksi tuettuna vain ”esihyväksytty” -hyväksyntävaihe. Rajapinnoissa tuetaan muitakin hyväksyntävaiheita, kun ne toteutetaan latausprosessissa.