Harmonisoidut rajapinnat
Kaikissa Yhteentoimivuusalustan sovelluksissa on harmonisoitu Integration-rajapinta, jonka avulla voidaan hakea tietosisältöjen perustietoja samassa formaatissa. Integration API:t tukevat GET- ja POST-tyyppisiä kyselyjä, joiden avulla alustalta voidaan kysellä lista kaikista tuotoksista (Containers) ja niissä määriteltävistä resursseista (Resources).
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"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"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"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"Alun perin resurssien 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: */*"
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.
Tilakoodi | Nimi | Tilan tarkoitus |
|---|---|---|
INCOMPLETE | Keskeneräinen | Keskeneräinen ja kirjautumattomilta käyttäjiltä piilotettu resurssi, johon ei vielä kannata tehdä viittauksia. |
DRAFT | Luonnos | Sanastot- ja Koodistot-työkaluissa oleva julkinen luonnos, jonka ulkopuolisetkin näkevät, mutta johon vielä voi tulla muutoksia. jota voidaan käyttää. Näissä työkaluissa luonnos voidaan poistaa tai korvata toisella. Tietomallit-työkalussa luonnos on työstöversio, joka ei näy oman organisaation ulkopuolisille käyttäjille. |
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 | Tietomalleissa julkinen versio, joka on julkaistu kommentoitavaksi, mutta johon voi tulla muutoksia. Se voidaan poistaa tai korvata toisella tietomallilla. |
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:
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 |
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>