Finlexin aineistoja avoimena datana ohjelmallisesti tai käyttöliittymän kautta ladattavissa
Finlexin aineistot ovat saatavilla verkkopalvelun lisäksi myös avoimena datana. Aineistoja voi ladata sekä ohjelmallisesti REST-rajapinnan kautta tekemällä erilaisia hakuja että aineistokohtaisina paketteina käyttöliittymän kautta.
Avoimen datan dokumentit ovat Akoma Ntoso xml-muodossa ja sen mukaisessa kansiorakenteessa. Toteutus on kansainvälisestä standardista Finlexiin tehty sovitus.
REST-rajapinnan kautta ladattava aineisto päivittyy pienellä viiveellä dokumentin julkaisusta. Käyttöliittymän kautta ladattavat paketit päivittyvät kerran vuorokaudessa.
Tutustu REST-rajapintakuvaukseen ja esimerkkiin Akoma Ntoso xml-dokumentista. Tutustu myös Akoma Ntoso -skeemaan ja Akoma Ntoso -standardiin.
Pääset integraation toteuttamisessa alkuun seuraamalla pikaopasta.
Rajapinnan sivutus on muuttunut ja page-parametri poistettu käytöstä.
Kuten aiemmin on tiedotettu, sivutus toimii jatkossa niin, että lastSeen-parametrillä annetaan viimeksi nähty dokumentti. Limit-parametrilla ilmaistaan edelleen, kuinka monta dokumenttia yhteen sivuun halutaan.
Lisäksi käyttöön on otettu lastSeenDateIssued- ja lastSeenModified-parametrit. Niitä on tarkoitus käyttää, jos käytetään modified- tai dateIssued-järjestämistapaa tuloksissa, joissa halutaan käyttää myös sivutusta. Sivutukseen tulee tällöin antaa sekä lastSeen-parametri että käytetystä järjestämistavasta riippuen myös lastSeenDateIssued tai lastSeenModified-parametri.
Finlexin avoimen datan rajapinnan sivutuslogiikkaan on tulossa muutos viikolla 47. Nykyisestä sivunumeroon perustuvasta sivutuksesta (page) siirrytään avainpohjaiseen sivutukseen (keyset).
Muutos on rikkova (breaking change), joten se edellyttää muutoksia kaikilta rajapintaa käyttäviltä järjestelmiltä.
Mitä muuttuu?
Rajapintakyselyissä luovutaan page-parametrin käytöstä. Jatkossa tietueita haetaan sivuittain välittämällä pyynnössä edellisen sivun viimeisimmän tietueen akn uri seuraavan sivun lähtökohdaksi.
Miksi muutos tehdään?
Muutoksella parannetaan rajapinnan suorituskykyä, toimintavarmuutta ja sivutuksen ennakoitavuutta suurissa aineistoissa. Avainpohjainen sivutus toimii tehokkaammin kasvavissa tietomäärissä ja vähentää tilanteita, joissa aineiston muutokset voisivat vaikuttaa sivutettujen tulosten käsittelyyn.
Esimerkit kyselyistä
Aiempi toteutus (page-pohjainen):
HTTP
GET /finlex/avoindata/v1/akn/fi/act/statute-consolidated/list? format=json&limit=10&page=11673
Uusi toteutus (keyset-pohjainen):
HTTP
# Ensimmäinen sivu
GET /finlex/avoindata/v1/akn/fi/act/statute-consolidated/list?limit=10
# Toinen sivu (edellisen sivun viimeisen tietueen ID (akn uri) oli /akn/fi/act/statute-consolidated/1992/912)
GET /finlex/avoindata/v1/akn/fi/act/statute-consolidated/list?lastSeen=/akn/fi/act/statute-consolidated/1992/912&limit=10
Vaadittavat toimenpiteet rajapinnan käyttäjiltä
Päivitä koodin sivutuslogiikka: muuta sovelluksesi pyynnöt tallentamaan kunkin vastauksen viimeisen tietueen tunniste ja välittämään se seuraavan sivun kyselyssä.
Poista page-parametrin käyttö: varmista, että sovelluksesi ei enää luota sivunumeroihin pyyntöjä muodostaessaan.
/akn/fi/act/{actDocumentType} ja /akn/fi/act/{actDocumentType}/list- rajapintoihin on lisätty isInForce-parametri. Parametri on käytössä vain ajantasaistetuille säädöksille, joissa sillä voi rajata, haluaako hakea vain voimassa olevat tai voimasssa olemattomat ajantasaistetut säädökset.
@latest-parametria ja titleContains-parametria käyttävien kyselyiden suorituskykyä on parannettu
/list -rajapintoihin tullut uusi valinnainen hakuparametri documentNumber
sivutuksiin liittyvän Limit-parametrin maksimi on pienennetty 10:een sadasta
authority-regulation -rajapintoihin on lisätty main.akn-tuki, joka muilla aineistoilla jo oli
dateNoLongerInForce-kenttä vastauksissa on nimetty uudelleen nimelle dateInForceEnd
Aineistoille, joilla on xml- ja pdf-muotoinen sisältö, palautetaan xml-muotoinen esitys. Pelkän pdf-muotoisen esityksen sisältäville palautetaan xml-metadata, joka viittaa sisällön pdf-muotoiseen esitykseen.
Aineiston xml-, pdf- ja mediatiedostot zip-arkistona palauttavissa end pointeissa on muutettu zipin sisältämä hakemistorakenne siten, että pdf-tiedosto löytyy zipin juurihakemistosta erillisen alihakemiston sijaan.
End point akn/fi/act/<actDocumentType>/list listaa nyt myös ajantasaisten säädösten ajalliset versiot alkuperäisten kieliversioiden (ns. säädöskokoelma-versio) lisäksi.
Jos hakuparametrissa ei ole määritelty ajantasaisen säädöksen ajallista versiota (muoto esim. fin@<ajallinen versio>), palautetaan end pointeista alkuperäinen kieliversio (ns. säädöskokoelma-versio).
akn/fi/act/<actDocumentType>/list.End point /akn/fi/act/{actDocumentType}/{year}/{number}, jonka kautta voi palauttaa ajantasaisen säädöksen kaikki ajalliset versiot sisältää nyt sivutuksen riittävän pienellä sivukoolla. Tällöin saadaan haettua paljon ajallisia versioita sisältävät säädökset sivu kerrallaan ilman, että vastauksen koko kasvaa niin suureksi, että se aiheuttaa ongelmia.
Avoimen datan rajapinnan Swagger-ui käyttöliittymän xml-vastausten syntaksin korostus on poistettu käytöstä, jotta suurempien vastausten käsittely käyttöliittymässä olisi API:a testatessa nopeampaa.
