Pikaopas integraation toteutukseen

Finlexin avoimen datan rajapinta on avoimien standardien mukainen, ohjelmointikieli- ja alustariippumaton REST-rajapinta, jota kutsutaan REST- tai HTTP-clientilla. Rajapintaa kutsutaan ohjelmointikirjastoilla tai http-pohjaisten palveluiden testaus- ja komentorivityökaluilla (esim. curl, Postman).

Rajapinta on kuvattu Open API -standardin mukaisella rajapintakuvauksella, joka on tarkasteltavissa Finlexin avoimen datan palvelussa Swagger UI -työkalulla. Swagger UI on käytettävissä rajapintaa kutsuvan palvelun rakentamiseen ja sillä voi testata palvelua. Swagger UI tarjotaan osana avoimen datan palvelua.

Integraation toteutuksessa voi käyttää Open API -rajapintakuvausta hyödyntäviä työkaluja esimerkiksi clientin generointiin, mutta se ei ole välttämätöntä.

Rajapintakuvaus dokumentoi end pointit, niiden palauttamat HTTP-paluukoodit ja tietomuotojen määritykset. Rajapinta palauttaa Akoma Ntoso -standardin mukaisia xml-dokumentteja. Palvelun palauttamat aineistojen dokumentit ovat Akoma Ntoso xml -muotoa. Joillekin rajapinnan end pointeille tuetaan myös json-muotoa. Käytetyt tietomuodot kuvataan Open API -rajapintakuvauksesta.

Rajapintakuvaus ei sisällä Akoma Ntoso XML -skeema, jonka mukaisia xml-dokumentteja rajapinnan palauttamat vastaukset ovat.

Avoimen datan palvelun REST-rajapinnan end pointit on kuvattu Open API-kuvauksessa ja löytyvät osoitteesta https://opendata.finlex.fi/finlex/avoindata/v1

Finlexin avoimen datan rajapinta on kutsuttavissa https-protokollalla käyttäen TLS-protokollan versiota 1.2 tai uudempaa. Salaamaton http-protokolla ei ole tuettu. Rajapinnan käyttö ei edellytä tunnistautumista tai rekisteröitymistä.

Finlexin avoimen datan palvelun käyttövolyymeja saatetaan rajoittaa palvelun saatavuuden varmistamiseksi, mikä kannattaa ottaa huomioon palvelua käyttävissä client-toteutuksissa. Kutsujen määrää rajoittaessa palvelu palauttaa http-virhekoodin 429 Too Many Requests.

Yleisiä asioita Finlexin avoimen datan rajapinnan kutsumisesta:

• Kaikki kutsut vaativat 'User-Agent'-headerin asettamisen.
• Dokumenttien listaamisen mahdollistavat endpointit sisältävät sivutusmekanismin, joka perustuu API-kutsun query stringin parametreihin page ja limit.
  • Tämä mahdollistaa suurien hakutulosten palauttamisen sivu kerrallaan
  • Page-parametri on palautettavan hakutuloksen sivu. Ensimmäinen sivu on 1
  • Limit on sivun koko
  • Kaikki hakutulokset saa palautettua tekemällä peräkkäisiä kutsuja, joissa kasvatetaan sivunumeroa
  • Kun viimeinen sivu sisältää vähemmän hakutuloksia kuin sivun koko, ollaan saavuttu hakutuloksen loppuun.
• Jos avoimen datan rajapintaa kutsuvassa sovelluksessa käytetty REST- tai http-client sitä tukee, on suositeltavaa käyttää http-kehystietoa "Accept-Encoding: gzip". Näin suurikokoisten aineistojen lataaminen mahdollistuu ja helpottuu.
  • Huomioi, että käyttäjä ei pysty asettamaan Swagger-UI:n kautta kyseistä kehystietoa teknisistä syistä.
  • Ohjelmistopohjaisilla clienteilla ja REST- ja http-pohjaisten liittymien testaukseen tarkoitetuilla työkaluilla (esim. curl, Postman) kyseinen kehystieto on asetettavissa.
• Hakutulokset voi järjestää käyttämällä parametria sortBy. Parametrin arvo on enumeraatio, josta voi valita jonkin kentistä, jonka mukaan hakutulos järjestetään
• Rajapinnan palauttamat dokumentit sisältävät liitteitä ja kuvia. Osassa aineistoista leipäteksti on xml-dokumentin viittaamassa pdf-tiedostossa
  • Joissakin aineistoissa pdf on ainoa muoto ja joissakin se on tarjolla xml-muotoisen rinnalla
  • Kuviin, liitteisiin ja leipätekstin sisältäviin pdf-tiedostoihin viitataan suhteellisin hyperlinkein, joiden seuraamisen avoimen datan rajapinta mahdollistaa HATEOAS -periaatteen (Hypermedia as the engine of application state) mukaisesti
• Rajapinta sisältää endpointteja, jotka palauttavat yksittäisen aineiston zip-tiedostona, joka sisältää kyseisen aineiston kaikki liitteet, kuvat ja mahdolliset leipätekstin sisältävät pdf-tiedostot. Tämä mahdollistaa aineiston käsittelyn helpommin ilman yhteyttä Finlex avoimen datan palveluun.

Esimerkkejä avoimen datan rajapinnan kutsumisesta

Esimerkki rajapinnan kutsumisesta Suomen säädöskokoelman sisältämän vuoden 2024 alkuperäisen säädöksen numero 123 suomenkielisen kieliversion hakemiseksi

Haku tehdään lähettämällä http GET -kutsu seuraavaan end pointiin:

https://opendata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute/2024/123/fin%40

Kutsun tekeminen curl-komennolla:

curl -X 'GET' \
'https://opendata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute/2024/123/fin%40' \
-H 'accept: application/xml' -H 'User-Agent: curl'

Jos kutsu onnistuu, se vastaa palauttamalla seuraavan Akoma Ntoso xml -muotoisen dokumentin:

<akomaNtoso xmlns="http://docs.oasis-open.org/legaldocml/ns/akn/3.0" xmlns:finlex="http://data.finlex.fi/schema/finlex" xmlns:mylly="http://mylly.edita.fi/schema/mylly" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <act contains="originalVersion" name="main"> <meta> <identification source="#organization_fi.finlex"> <FRBRWork> <FRBRthis value="/akn/fi/act/statute/2024/123/!main"/> <FRBRuri value="/akn/fi/act/statute/2024/123"/> <FRBRalias name="eli" value="http://data.finlex.fi/eli/sd/2024/123/alkup"/> <FRBRdate date="2024-03-22" name="dateIssued"/> <FRBRdate date="2024-03-26" name="datePublished"/> <FRBRauthor as="#role_author" href="#organization_fi.parliament"/> <FRBRcountry value="fi"/> <FRBRsubtype value="statute"/> <FRBRnumber value="123"/> <FRBRprescriptive value="true"/> <FRBRauthoritative value="true"/> </FRBRWork> <FRBRExpression> <FRBRthis value="/akn/fi/act/statute/2024/123/fin@/!main"/> <FRBRuri value="/akn/fi/act/statute/2024/123/fin@"/> <FRBRalias name="eli" value="http://data.finlex.fi/eli/sd/2024/123/alkup/fin"/> <FRBRdate date="2024-03-22" name="dateIssued"/> <FRBRdate date="2024-03-26" name="datePublished"/> <FRBRauthor as="#role_author" href="#organization_fi.parliament"/> <FRBRlanguage language="fin"/> </FRBRExpression> <FRBRManifestation> <FRBRthis value="/akn/fi/act/statute/2024/123/fin@/!main.xml"/> <FRBRuri value="/akn/fi/act/statute/2024/123/fin@.akn"/> <FRBRalias name="eli" value="http://data.finlex.fi/eli/sd/2024/123/alkup/fin/xml"/> <FRBRdate date="2024-09-19" name="dateProduced"/> <FRBRauthor as="#role_editor" href="#organization_fi.finlex"/> <FRBRformat value="xml"/> </FRBRManifestation> </identification> <references source="#organization_fi.finlex"> <original eId="original" href="/akn/fi/act/statute/2024/123/fin@" showAs="123/2024"/> <activeRef eId="activeRef" href="/akn/fi/act/statute/2023/1247" showAs="1247/2023"/> <TLCOrganization eId="organization_fi.finlex" href="/akn/ontology/organization/fi.finlex" showAs="Finlex"/> <TLCOrganization eId="organization_fi.parliament" href="/akn/ontology/organization/fi.parliament" showAs="Eduskunta"/> <TLCRole eId="role_author" href="/akn/ontology/role/author" showAs="Tekijä"/> <TLCRole eId="role_editor" href="/akn/ontology/role/editor" showAs="Toimittaja"/> <TLCConcept eId="concept_statute_type-statute.decree" href="/akn/ontology/concept/statute/type-statute.decree" showAs="Asetus"/> <TLCConcept eId="concept_statute_category-statute.amending-statute" href="/akn/ontology/concept/statute/category-statute.amending-statute" showAs="Muutossäädös"/> </references> <proprietary source="#organization_fi.finlex"> <finlex:typeStatute refersTo="#concept_statute_type-statute.decree"/> <finlex:documentYear>2024</finlex:documentYear> <finlex:legacyFinlexUrl>/fi/laki/alkup/2024/20240123</finlex:legacyFinlexUrl> <finlex:categoryStatute refersTo="#concept_statute_category-statute.amending-statute"/> </proprietary> </meta> <preface> <p> <docNumber>123/2024</docNumber> <docTitle>Työ- ja elinkeinoministeriön asetus Patentti- ja rekisterihallituksen maksullisista suoritteista vuonna 2024 annetun työ- ja elinkeinoministeriön asetuksen muuttamisesta</docTitle> </p> </preface> <body> <hcontainer name="statuteTextWrapper"> <content> <p>Tämä asetus tulee voimaan 1 päivänä huhtikuuta 2024. Asetus on voimassa 31 päivään joulukuuta 2024 saakka.</p> </content> </hcontainer> </body> </act> </akomaNtoso>

Koska kyseinen end point käyttää GET http -metodia, onnistuu kutsuminen myös avaamalla end point URL selaimella.

Esimerkki vuoden 2024 Suomen säädöskokoelman säädösten listaamisesta

Alla esimerkki Suomen säädöskokoelman vuoden 2024 uusien säädösten listaamisesta json-muodossa. Listauksen tarjoava rajapinta palauttaa listan säädöskokoelman säädösten xml-dokumentteihin, jotka sopivat annettuihin hakuehtoihin.

Rajapinta sivuttaa listauksen annetulla sivukoolla ja tämä kutsu palauttaa ensimmäisen sivun. Seuraavan sivun voi hakea vaihtamalla sivunumeroa.

Kuva kutsun parametreista Swagger UI:sta:

Kutsu tapahtuu tekemällä http-palvelupyyntö GET-metodilla seuraavaan URL:iin:

https://opendata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute/list?format=json&page=1&limit=5&sortBy=dateIssued&startYear=2024&endYear=2024&langAndVersion=fin%40&typeStatute=act&categoryStatute=new-statute

Kutsun tekeminen curl-komennolla:

curl -X 'GET' \
'https://opendata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute/list?format=json&page=1&limit=5&sortBy=dateIssued&startYear=2024&endYear=2024&langAndVersion=fin%40&typeStatute=act&categoryStatute=new-statute' \
-H 'accept: application/xml' -H 'User-Agent: curl'

Esimerkkivastaus:

[
  {
    "akn_uri": "https://avoindata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute/2024/2/fin@",
    "status": null
  },
  {
    "akn_uri": "https://avoindata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute/2024/18/fin@",
    "status": null
  },
  {
    "akn_uri": "https://avoindata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute/2024/24/fin@",
    "status": null
  },
  {
    "akn_uri": "https://avoindata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute/2024/17/fin@",
    "status": null
  },
  {
    "akn_uri": "https://avoindata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute/2024/124/fin@",
    "status": null
  }
]

Esimerkki Metsähallituksen vuoden 1998 viranomaismääräyksen numero 32082 tekstisisällön sisältävän pdf-tiedoston hakemisesta avoimen datan palvelun kautta:

URL-osoite, johon tehdään http-palvelupyyntö GET-metodilla:

https://opendata.finlex.fi/finlex/avoindata/v1/akn/fi/doc/authority-regulation/metsahallitus/1996/32082/fin%40/main.pdf

Kutsun tekeminen curl-komennolla:

curl -X 'GET' \
'https://opendata.finlex.fi/finlex/avoindata/v1/akn/fi/doc/authority-regulation/metsahallitus/1996/32082/fin%40/main.pdf' \
-H 'accept: application/pdf' -H 'User-Agent: curl'

Esimerkki tieliikennelain (2018/729) ajantasaisen suomenkielisen kieliversion hakemisesta kuvineen ja liitteineen zip-tiedostona:

End pointin parametrit Swagger UI:ssa:

URL-osoite, johon tehdään http-palvelupyyntö GET-metodilla:

https://opendata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute-consolidated/2018/729/fin%40/main.akn

Kutsun tekeminen curl-komennolla:

curl -X 'GET' \
'https://opendata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute-consolidated/2018/729/fin%40/main.akn' \
-H 'accept: application/zip' -H 'User-Agent: curl'

Esimerkki tieliikennelain (2018/729) ajantasaisen suomenkielisen kieliversion yhden kuvatiedoston hakeminen avoimen datan rajapinnan kautta:

Tätä operaatioita voi käyttää Akoma Ntoso -dokumenttien sisältämien kuvien ja liitetiedostojen hakemiseen linkkiä seuraamalla HATEOAS-periaatteen (Hypermedia as the engine of application state) mukaisesti.

URL-osoite, johon tehdään http-palvelupyyntö GET-metodilla:

https://opendata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute-consolidated/2018/729/fin%40/media/7296.gif

Kutsun tekeminen curl-komennolla:

curl -X 'GET' \
'https://opendata.finlex.fi/finlex/avoindata/v1/akn/fi/act/statute-consolidated/2018/729/fin%40/media/7296.gif' \
-H 'accept: image/gif' -H 'User-Agent: curl'

Kutsu palauttaa yksittäisen gif-kuvan, joka sisältyy tieliikennelakiin. Tarkoituksenmukainen tapa tehdä tämä kutsu on seurata edellisen esimerkin noutaman Akoma Ntoso -dokumentin sisältämää linkkiä kyseiseen kuvaan.