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, jonka organisaation pääkäyttäjä voi tilata Yhteentoimivuusalustan oikeuksienhallintasovelluksen kautta (eli ns. ryhmienhallintapalvelusta): https://rhp.suomi.fi.
Näin tilaat tokenin:
- 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.
Sovellus | Kuvaus | Linkki |
---|---|---|
Tietomallit | Tietomallit-sovelluksen API -kuvaus | https://tietomallit.suomi.fi/swagger/ |
Koodistot | Koodistot-sovelluksen API -kuvaus | https://koodistot.suomi.fi/swagger/ |
Sanastot | Sanastot-sovelluksen API -kuvaus | https://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- rajapintaesimerkki:
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-rajapintaesimerkki (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-rajapintaesimerkki:
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-rajapintaesimerkki (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"
Usage API
Alun perin resurssien ym. käyttöön liittyviä tietoja on haettu rajapinnoista rajaamalla ne yhdellä parametrilla. Syyskuussa 2021 rajapintoja täydennettiin niin, että tietyissä tapauksissa se tukee usean parametrin käyttöä. Näin esimerkiksi voidaan hakea tiettyyn tietomalliin liittyvät käsitteet.
Esimerkkejä:
# Käsite & tietomalli:
curl -X GET "https://tietomallit.test.yti.cloud.vrk.fi/datamodel-api/api/v1/usage?model=http%3A%2F%2Furi.suomi.fi%2Fdatamodel%2Fns%2Fjhs&concept=http%3A%2F%2Furi.suomi.fi%2Fterminology%2Fjhs%2FJ754" -H "accept: */*"
# Resurssi & tietomalli:
curl -X GET "https://tietomallit.test.yti.cloud.vrk.fi/datamodel-api/api/v1/usage?id=http%3A%2F%2Furi.suomi.fi%2Fdatamodel%2Fns%2Fjhs%23Henkilo&model=http%3A%2F%2Furi.suomi.fi%2Fdatamodel%2Fns%2Fjhs" -H "accept: */*"
# Pelkkä tietomalli:
curl -X GET "https://tietomallit.test.yti.cloud.vrk.fi/datamodel-api/api/v1/usage?model=http%3A%2F%2Furi.suomi.fi%2Fdatamodel%2Fns%2Fjhs" -H "accept: */*"
# Pelkkä käsite:
curl -X GET "https://tietomallit.test.yti.cloud.vrk.fi/datamodel-api/api/v1/usage?concept=http%3A%2F%2Furi.suomi.fi%2Fterminology%2Fjhs%2FJ754" -H "accept: */*"
# Pelkkä resurssi:
curl -X GET "https://tietomallit.test.yti.cloud.vrk.fi/datamodel-api/api/v1/usage?id=http%3A%2F%2Furi.suomi.fi%2Fdatamodel%2Fns%2Fjhs%23Henkilo" -H "accept: */*"
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:
Tilakoodi | Nimi | Tilan tarkoitus |
---|---|---|
INCOMPLETE | Keskeneräinen | Keskeneräinen ja kirjautumattomilta piilotettu resurssi jota ei vielä kannata käyttää |
DRAFT | Luonnos | Julkinen luonnos jota voidaan käyttää. Luonnos on kuitenkin keskeneräinen tuotos joka voidaan poistaa tai korvata toisella. |
VALID | Voimassa oleva | Organisaation hyväksymä resurssi jota voi käyttää |
SUPERSEDED | Korvattu | Korvattu resurssi jota ei kannata käyttää |
RETIRED | Poistettu käytöstä | Poistettu resurssi jota ei kannata käyttää |
INVALID | Virheellinen | Virheellinen resurssi jota ei kannata käyttää |
SUGGESTED | Ehdotus | Sanastoon 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 alla olevassa taulukossa esitettyjä sovelluksia ja formaatteja.
Tietomallit | Sanastot | Koodistot |
---|---|---|
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>