Sökning av uppgifter i rest-gränsnittet
Godkända uppgifter som har överförts till registertjänsten är tillgängliga via rest-gränssnittet i JSON- och XML-format.
Sökningen av nyckelvärden via rest-gränssnittet sker i två steg.
- Först söker man i alla materialuppgifter som finns i tjänsten.
2. Därefter kan man välja det önskade materialet med hjälp av resultatgruppens koduppgifter (FO-nummer, rapporteringshelhet etc.). För resultatgruppen finns en färdig URL-adress med vilken man kan leta efter nyckelvärden för just det aktuella materialet.
Hur man söker information beror naturligtvis också på vilken applikation eller webbläsare man använder för att söka informationen.
Rest-gränssnittets adress
Rest-gränssnittet finns på adressen: https://kuntarestusertest.westeurope.cloudapp.azure.com/.
När man går till adressen öppnas vyn nedan med anvisningar för användning av gränssnittet.
Bild 1 Startsida för registertjänstens startsida
I produktionsbruk är uppgifterna tillgängliga för alla via gränssnittet. Tillträdet till user test-miljön (https://kuntarestusertest.westeurope.cloudapp.azure.com/) begränsas tills vidare av en brandvägg. För att kunna testa gränssnittstjänsten ska ni meddela IP-adressen till er organisations brandvägg till Statskontorets e-postadress
kuntadata@valtiokonttori.fi.
Sökning av materialuppgifter och exempelsökningar
I sökningen av materialuppgifter används följande parametrar:
- Version: v1
- ormat: json eller xml (senare även xbrl och jxbrl)
- Material nyckelord: aineistot, collection, samling
Utgående från ovan nämnda parametrar kan alla materialuppgifter som finns i tjänsten sökas:
https://kuntarestusertest.westeurope.cloudapp.azure.com/rest/<version>/<format>/<material-nyckelord>. Dessa tecken bör inte användas för riktiga adresser.
1. I JSON-format: https://kuntarestusertest.westeurope.cloudapp.azure.com/rest/v1/json/aineistot
2. I XML-format: https://kuntarestusertest.westeurope.cloudapp.azure.com/rest/v1/xml/aineistot.
Nedan har vi som exempel sökt samma materialuppgifter med några olika applikationer.
Exempel 1. Sökning av materialuppgifter i JSON-format i webbläsaren Firefox.
När du i Firefox går till ovan nämnda adress https://kuntarestusertest.westeurope.cloudapp.azure.com/rest/v1/json/aineistot, öppnas en textvy i JSON-format
Bild 2 Sökning av materialuppgifter i JSON-format i webbläsaren Firefox.
Till Firefox finns även tillägg med vilka man kan få JSON-formatet att visas med prydligare formatering.
Bild 3 Visning av JSON-format med prydligare formatering
Exempel 2. Sökning av materialuppgifter i JSON-format med Internet Explorer.
Webbläsaren IE föreslår att de materialuppgifter som söks på adressen (aineistot.json) ska öppnas i arbetsstationens applikation eller sparas på arbetsstationen.
Bild 4 Sökning av materialuppgifter i JSON-format med Internet Explorer, laddningsfönster
Efter sökningen kan materialuppgifterna öppnas i en applikation på arbetsstationen (t.ex. anteckningar).
Bild 5 Sökning av materialuppgifter i JSON-format med Internet Explorer
Exempel 3. Sökning av materialuppgifter i JSON-format med applikationen SoapUI.
Materialuppgifter kan sökas med kommandot:
GET https://kuntarestusertest.westeurope.cloudapp.azure.com/rest/v1/json/aineistot HTTP/1.1.
Bild 6 Sökning av materialuppgifter i JSON-format med applikationen SoapUI
I gränssnittet finns även inbjudningar på engelska och svenska:
https://kuntarestusertest.westeurope.cloudapp.azure.com/rest/v1/json/collection
https://kuntarestusertest.westeurope.cloudapp.azure.com/rest/v1/json/samling
Tolkning av materialuppgifter
I materialuppgifterna finns information om allt material i registertjänsten, och följande uppgifter för varje material:
- FO-nummer (Y-tunnus)
- Rapporteringshelhet (Raportointikokonaisuus)
- Rapporteringsperiod (Raportointikausi)
- Godkännandeskede (Hyväksyntävaihe)
- Tid för godkännande (Hyväksymisaika)
- URL-adress för nyckelvärdet (URL-osoite tunnuslukuja varten)
Resultatuppsättningen identifierare (FO-nummer, rapporteringshelhet osv.) används för att välja de uppgifter som krävs, och en föraggregerad URL kan användas för att söka efter relevanta data. Färdiga sökadresser använder samma överföringsformat som användes för att söka efter all data. Om alla data har begärts i json-format, parametreras även URL:erna i datalistan för json-baserade KI-listor. URL-anrop för data i främmande språk hänvisar också till icke-språkliga nyckelkodsamtal. Det är lätt att skapa en URL som hämtar nyckelnumren per maskin. Detta är fallet om du vill ändra parametervärdena för det färdiga nyckelvärdet sökningen (till exempel språket i kontrollfallen).
Den tidigare resultatuppsättningen innehöll endast en data, vars nyckeltal kan sökas på följande adress: https://kuntarestusertest.westeurope.cloudapp.azure.com/rest/v1/json/dokumentti/lopullinen/ktas/0186588-2/2019.
Bild 7 Tolkning av materialuppgifter
Från ovanstående exempelsökning bör det noteras att API-sökningar som ges som exempel har implementerats med testdata, så att sökningarna kanske inte returnerar samma resultat i den verkliga miljön.
Sökning av nyckelvärden som hör till ett visst material
Sökningen av materialuppgifter beskrevs ovan. Man kan välja det önskade materialet med hjälp av resultatgruppens koduppgifter (FO-nummer, rapporteringshelhet etc.). För resultatgruppen finns också en färdig URL-adress med vilken man kan leta efter nyckelvärden för det aktuella materialet.
I den färdiga sökningsadressen för nyckelvärden används samma överföringsform som användes för att söka allt material. Om alla material har begärts i JSON-format kommer URL-adresserna i materiallistorna i fråga också att vara parametriserade för JSON-baserade listor över nyckelvärden. En URL-adress som söker nyckelvärden kan enkelt bildas även maskinellt. Man måste göra på detta sätt om man vill ändra parametervärdena för en färdig sökning av nyckelvärden (såsom granskningshändelsernas språk).
I sökningen av nyckelvärden för material används följande parametrar:
- Version: v1
- Format: json, xml(senare även xbrl och jxbrl)
- Dokument Nyckelord: dokumentti, document eller dokument
- Godkännandeskede, finska: esi, alustava, hyväksytty, lopullinen.
- Godkännandeskede, engelska: initial, approved, final
- Godkännandeskede, svenska: preliminär, godkänt, slutlig
- Rapporteringshelhet: ktas (andra stöds för närvarande inte)
- FO-numret: kommunens FO-nummer, till exempel 0145208-4
- Period: 2018, 2019 osv.
Dokumentnyckelordet och godkännandesteget måste skrivas på samma språk så att systemet känner igen begäran korrekt. Till exempel dokumentti och lopullinen, document och
final eller dokument och slutlig.
Även om sökningen av nyckelvärdet utförs på ett främmande språk, är kommentarfältet i resultaten endast på det språk där kommentaren skrev den. Systemet översätter inte kommentarer till önskat språk.
Tolkning av nyckelvärden som hör till ett visst material
I resultaten av en sökning av nyckelvärden är följande uppgifter tillgängliga:
- FO-nummer
- Rapporteringshelhet
- Rapporteringsperiod
- Godkännandeskede
- Tid för godkännande
- Taxonomi
- Nyckelvärde (sifferkod enligt taxonomin)
- Nyckelvärdets värde
- Anmälan om granskningshändelse
- Precisering av granskningshändelse
- Granskningshändelsens allvarlighet
- Granskningshändelsens språk
Nedan visas uppgifter från en exempelobservation.
Bild 8 Nyckelvärdesuppgifter för exempelobservation
Tills vidare (24.1.2020) stöds endast godkännandeskedet ”godkänt i förväg” i uppladdningen av ekonomisk information. I gränssnitten stöds även andra godkännandeskeden när de förverkligas i laddningsprocessen.