Tietojen haku rest-rajapinnasta
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://kuntarestusertest.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. Toistaiseksi pääsyä user test -ympäristöön (https://kuntarestusertest.westeurope.cloudapp.azure.com/) on rajoitettu palomuurilla. Päästäksenne testaamaan rajapintapalvelua, ilmoittakaa organisaationne palomuurin IP-osoite Valtiokonttorin sähköpostiosoitteeseen
kuntadata@valtiokonttori.fi.
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://kuntarestusertest.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://kuntarestusertest.westeurope.cloudapp.azure.com/rest/v1/json/aineistot
2. XML-muodossa:
https://kuntarestusertest.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://kuntarestusertest.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://kuntarestusertest.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://kuntarestusertest.westeurope.cloudapp.azure.com/rest/v1/json/collection
https://kuntarestusertest.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:
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 ovat 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
lopullinen,
document 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.