Skip to end of metadata
Go to start of metadata

Tällä sivulla on kuvattu miten alustan rajapintoja voidaan hyödyntää ulkopuolisissa integraatioissa, kuten koodistojen, tietomallien tai sanastojen lataamisessa omaan tietojärjestelmään tai aineistojen automaattiseen päivittämiseen yhteentoimivuusalustalle.

Tokenin tilaaminen

Rajapintoja voidaan käyttää JWT-tokenin avulla, joka voidaan tilata Yhteentoimivuusalustan oikeuksienhallintasovelluksesta (eli ns. ryhmienhallintapalvelusta): https://rhp.suomi.fi.

  • Kirjaudu sisään oikeuksienhallintasovellukseen
  • Valitse oikeassa ylänurkassa olevasta valikosta kohta Käyttäjätiedot.
  • Siirryt Käyttäjätiedot -sivulle. Siirry sivulla alaspäin.
  • Roolitietojesi listan alla on otsikko API-avain. Napsauta Luo API-avain-painiketta.

Tilattu token näytetään tokenia luotaessa vain kerran, mutta sen voi tarvittaessa poistaa ja luoda uudelleen.


Rajapintojen Open API kuvaukset

Allaolevat linkit tarjoavat Swagger UI -käyttöliittymän sekä Try it out -toiminnon rajapintojen kokeilemista varten.

SovellusKuvausLinkki
TietomallitTietomallit-sovelluksen API -kuvaushttps://tietomallit.suomi.fi/swagger/
KoodistotKoodistot-sovelluksen API -kuvaushttps://koodistot.suomi.fi/swagger/ 
SanastotSanastot-sovelluksen API -kuvaushttps://sanastot.suomi.fi/swagger/ 

Harmonisoidut rajapinnat

Kaikissa sovelluksissa on harmonisoitu Integration-rajapinta, jonka avulla voidaan hakea tietosisältöjen perustietoja samassa formaatissa. Integration API:t tukevat sekä GET että POST tyyppisiä kyselyjä, joiden avulla alustalta voidaan kysellä lista kaikista tuotoksista (Containers) ja niissä määriteltävistä resursseista (Resources). 

Containers API - /api/v1/integration/containers

API listaa kaikki julkaistut aineistot (containers). 

GET rajapinta esimerkki:

Tietomallit

curl -X GET "https://tietomallit.suomi.fi/datamodel-api/api/v1/integration/containers" -H "Content-Type: application/json" -H "Authorization: Bearer INSERT_TOKEN_HERE"

Koodistot

curl -X GET "https://koodistot.suomi.fi/codelist-api/api/v1/integration/containers" -H "Content-Type: application/json" -H "Authorization: Bearer INSERT_TOKEN_HERE"

Sanastot

curl -X GET "https://sanastot.suomi.fi/terminology-api/api/v1/integration/containers" -H "Content-Type: application/json" -H "Authorization: Bearer INSERT_TOKEN_HERE"

Kommentit

curl -X GET "https://kommentit.suomi.fi/comments-api/api/v1/integration/containers" -H "Content-Type: application/json" -H "Authorization: Bearer INSERT_TOKEN_HERE"

POST rajapinta esimerkki (Tietomallit):

curl -X POST "https://tietomallit.test.yti.cloud.vrk.fi/datamodel-api/api/v1/integration/containers" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"searchTerm\":\"tieto\",\"pageSize\":5,\"pageFrom\":0}" -H "Authorization: Bearer INSERT_TOKEN_HERE"

Resources API - /api/v1/integration/resources

API listaa kaikki tuotoksissa julkaistut resurssit (resources). 

GET rajapinta esimerkki:

Tietomallit

curl -X GET "https://tietomallit.test.yti.cloud.vrk.fi/datamodel-api/api/v1/integration/resources?after=2018-11-19T13%3A26%3A13.057Z&before=2019-01-19T13%3A26%3A13.057Z" -H "Authorization: Bearer INSERT_TOKEN_HERE"

Koodistot

curl -X GET "https://koodistot.test.yti.cloud.vrk.fi/codelist-api/api/v1/integration/resources?after=2018-11-19T13%3A26%3A13.057Z&before=2019-01-19T13%3A26%3A13.057Z" -H "Authorization: Bearer INSERT_TOKEN_HERE"

Sanastot

curl -X GET "https://sanastot.test.yti.cloud.vrk.fi/terminology-api/api/v1/integration/resources?after=2018-11-19T13%3A26%3A13.057Z&before=2019-01-19T13%3A26%3A13.057Z" -H "Authorization: Bearer INSERT_TOKEN_HERE"

Kommentit

curl -X GET "https://kommentit.test.yti.cloud.vrk.fi/comments-api/api/v1/integration/resources?after=2018-11-19T13%3A26%3A13.057Z&before=2019-01-19T13%3A26%3A13.057Z" -H "Authorization: Bearer INSERT_TOKEN_HERE"

POST rajapinta esimerkki (Tietomallit):

curl -X POST "https://tietomallit.test.yti.cloud.vrk.fi/datamodel-api/api/v1/integration/resources" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"status\":[\"DRAFT\",\"VALID\"],\"after\":\"2018-11-19T14:05:19.451Z\",\"before\":\"2019-01-19T14:05:19.451Z\"}" -H "Authorization: Bearer INSERT_TOKEN_HERE"

Aineiston hakeminen ja filtteröinti


Aineistoja voidaan hakea /containers ja /resources api:ssa searchTerm parametrin avulla. Vakiona rajapinta palauttaa korkeintaan 50 000 objektia. Sivutusta voidaan säätää pageSize ja from parametrien avulla.

Aineistoja voidaan suodattaa muokkausajan mukaan after ja before parametrien avulla, antamalla aikaleima ISO 8601 / XSD datetime muodossa.

Haettuja aineistoja voidaan myös suodattaa tilan eli status parametrin avulla, määrittelemällä yksi tai useampi tilakoodi. Vakiona palautetaan kaikki muut paitsi keskeneräiset aineistot. Keskeneräiset voidaan palauttaa helposti includeIncomplete parametrin avulla. Keskeneräisiä aineistoja ei kuitenkaan yleensä kannata käyttää, ellei kyseessä ole oman organisaation projekti.


Tilakoodit:

TilakoodiNimiTilan tarkoitus
INCOMPLETEKeskeneräinenKeskeneräinen ja kirjautumattomilta piilotettu resurssi jota ei vielä kannata käyttää
DRAFTLuonnosJulkinen luonnos jota voidaan käyttää. Luonnos on kuitenkin keskeneräinen tuotos joka voidaan poistaa tai korvata toisella.
VALIDVoimassa olevaOrganisaation hyväksymä resurssi jota voi käyttää
SUPERSEDEDKorvattuKorvattu resurssi jota ei kannata käyttää 
RETIREDPoistettu käytöstäPoistettu resurssi jota ei kannata käyttää
 INVALID Virheellinen Virheellinen resurssi jota ei kannata käyttää
 SUGGESTED EhdotusSanastoon käyttäjän toimesta ehdotettu käsite. Käytössä vain sanastoissa! Keskeneräinen tuotos joka voidaan poistaa tai korvata toisella.


Aineiston resolvointi uri:n avulla


Harmonisoidut integration-rajapinnat tarjoavat yksinkertaisen tavan listata aineistot. Listauksen perusteella voidaan hakea tarkempia julkaisukohtaisia tietoja resolvoimalla aineisto URI-tunnuksen avulla.


Esimerkki aineiston URI osoitteen resolvoinnista:

curl -L -X GET --header 'Accept: application/json' 'http://uri.suomi.fi/datamodel/ns/att#'

Resolvoinnissa tuetut formaatit

Tällä hetkellä resolvoinnissa tuetaan seuraavia sovelluksia ja formaatteja.

TietomallitSanastotKoodistot
application/schema+json
application/json
application/json
application/ld+json
application/xml

application/ld+json+context
application/rdf+xml

application/xml


application/ld+json+context


application/vnd+oai+openapi+json


 text/turtle


 application/rdf+xml



Sovelluskohtaiset Export API:t

Sovelluksista voidaan exportoida aineistoja myös sovelluskohtaisten export API:en avulla.

Tietomallit:

Open API Dokumentaatio: https://tietomallit.suomi.fi/datamodel-api/swagger-ui/index.html#/Model/getExportModel

Polku: /datamodel/api/v1/exportModel?uri=<http://...>

Sanastot:

/api/v1/export/{terminologyID}?format=<JSON,RDF,TURTLE>

Koodistot:

/codelist-api/api/v1/coderegistries/<rekisterin-tunniste>/codeschemes/<koodiston-tunniste>/?format=<excel|csv>





  • No labels