Snabbguide för integration

Finlex gränssnitt för öppna data är ett REST-gränssnitt som är förenligt med öppna standarder och oberoende av programmeringsspråk och plattform. Det anropas med REST- eller HTTP-klienter. Gränssnittet anropas med programbibliotek eller med test- och kommandoradsverktyg för HTTP-baserade tjänster (t.ex. curl, Postman).

För gränssnittet har en gränssnittsbeskrivning upprättats enligt Open API-standarden. Använd verktyget Swagger UI om du vill bekanta dig med beskrivningen. Swagger UI kan användas för att bygga upp en tjänst för anrop av gränssnittet och för att testa tjänsten. Swagger UI tillhandahålls som en del av Finlex tjänst för öppna data.

Vid integrationen kan verktyg som utnyttjar Open API-gränssnittsbeskrivningen användas till exempel för att generera klienter, men det är inte nödvändigt.

I gränssnittsbeskrivningen finns slutpunkter (endpoints), HTTP-returkoder och definitioner av dataformat dokumenterade. Gränssnittet returnerar XML-dokument som är förenliga med Akoma Ntoso-standarden. De dokument som tjänsten returnerar är alltid i Akoma Ntoso XML-format. Vissa slutpunkter i gränssnittet stöder också JSON-format. De använda dataformaten anges i Open API-gränssnittsbeskrivningen.

Gränssnittsbeskrivningen innehåller inte ett Akoma Ntoso XML-schema för de XML-dokument som gränssnittet returnerar.

Slutpunkterna för REST-gränssnittet i tjänsten för öppna data har beskrivits i Open API-beskrivningen och finns på adressen https://opendata.finlex.fi/finlex/avoindata/v1.

Finlex gränssnitt för öppna data kan anropas med HTTPS-protokoll, genom användning av protokollet TLS 1.2 eller nyare. Okrypterade HTTP-protokoll stöds inte. Användningen av gränssnittet kräver varken autentisering eller inloggning.

Användningsvolymerna i Finlex tjänst för öppna data kan begränsas för att säkerställa tillgången till tjänsten. Detta bör beaktas i de klientlösningar som använder tjänsten. Om antalet anrop begränsas ger tjänsten HTTP-felkoden 429 Too Many Requests.

Allmänt om anrop av Finlex gränssnitt för öppna data::

• Alla slutpunkter kräver att du ställer in 'User-Agent'-huvudet.
• De slutpunkter som gör det möjligt att lista dokument innehåller en mekanism för sidväxling som baserar sig på parametrarna page och limit i API-anropets frågesträng.
  • Detta gör det möjligt att returnera omfattande sökresultat en sida åt gången.
  • Parametern page är den sida med sökresultat som returneras. Den första sidan är 1.
  • Limit är sidstorleken.
  • Alla sökresultat kan returneras genom på varandra följande anrop som får sidnumret att bli större.
  • Slutet av sökresultatet har nåtts när den sista sidan innehåller färre sökresultat än sidstorleken.
• Om REST eller http-klient som används för att anropa gränssnittet för öppna data stöder det, rekommenderas att http-headern "Accept-Encoding: gzip" används. På detta sätt blir det möjligt och lättare att ladda ned material av stor storlek.
  • Observera att användaren inte kan ställa in denna header via Swagger-UI av tekniska skäl.
  • Headern kan ställas in med programvarubaserade klienter och test- och kommandoradsverktyg för http-baserade tjänster (t.ex. curl, Postman).
• Sökresultaten kan sorteras med parametern sortBy. Parametervärdet är en enumeration där du kan välja vilket fält som ska användas för sortering av sökresultatet.
• De dokument som gränssnittet returnerar innehåller bilagor och bilder. I en del material finns brödtexten i den pdf-fil som XML-dokumentet hänvisar till.
  • I vissa material är pdf det enda formatet som finns att tillgå, och i andra material tillhandahålls pdf vid sidan av XML-format.
  • Till bilder, bilagor och pdf-filer med brödtext hänvisas med relativa hyperlänkar som gränssnittet för öppna data möjliggör i enlighet med HATEOAS-principen (Hypermedia as the engine of application state).
• Gränssnittet innehåller slutpunkter som returnerar ett enskilt material som en zip-fil som innehåller alla bilagor, bilder och eventuella pdf-filer med brödtexten. Det gör det möjligt att lättare behandla materialet utan kontakt till Finlex tjänst för öppna data.

Esimerkkejä avoimen datan rajapinnan kutsumisesta

Exempel på anrop av gränssnittet för sökning av den finska versionen av den ursprungliga författningen 123/2024 i Finlands författningssamling:

Sökningen görs genom att skicka ett HTTP GET-anrop till följande slutpunkt:

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

Anrop med curl-kommandot:

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'

Om anropet lyckas returneras följande Akoma Ntoso XML-dokument:

<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>

Eftersom denna slutpunkt använder GET HTTP-metoden kan man också göra anropet genom att öppna slutpunktens URL i webbläsaren.

Exempel på lista över 2024 års författningar i Finlands författningssamling:

Nedan visas ett exempel på en lista över 2024 års författningar i Finlands författningssamling i JSON-format. Gränssnittet returnerar en lista över de författningar i författningssamlingen i XML-format som motsvarar sökvillkoren.

Gränssnittet gör en sidindelning av listan enligt angiven sidstorlek, och detta anrop returnerar den första sidan. Du får fram nästa sida genom att byta sidnummer.

Bild av anropets parametrar i Swagger UI:

Anropet sker genom en HTTP-begäran med GET-metoden till följande URL:

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

Anrop med curl-kommandot:

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'

Exempelsvar:

[
  {
    "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
  }
]

Exempel på hämtning av en pdf-fil med brödtexten i Forststyrelsens föreskrift nr 32082 från 1998 via tjänsten för öppna data:

URL för HTTP-begäran med GET-metoden:

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

Anrop med curl-kommandot:

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'

Exempel på hämtning av den uppdaterade finska versionen av vägtrafiklagen (729/2018) med bilder och bilagor som zip-fil:

Slutpunktens parametrar i Swagger UI:

URL för HTTP-begäran med GET-metoden:

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

Anrop med curl-kommandot:

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'

Exempel på hämtning av en bildfil i den uppdaterade finska versionen av vägtrafiklagen (729/2018) via gränssnittet för öppna data:

Denna operation kan användas för att hämta bilder och bilagor i Akoma Ntoso-dokument genom att följa länken i enlighet med HATEOAS-principen (Hypermedia as the engine of application state).

URL för HTTP-begäran med GET-metoden:

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

Anrop med curl-kommandot:

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'

Anropet returnerar en enskild gif-bild som ingår i vägtrafiklagen. Det bästa sättet att göra anrop är att följa länken till bilden i Akoma Ntoso-dokumentet i det föregående exemplet.