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.
...
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.
...
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).
...
API listaa kaikki julkaistut aineistot (containers).
GET rajapinta esimerkki- rajapintaesimerkki:
Tietomallit
| Code Block |
|---|
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
| Code Block |
|---|
curl -X GET "https://koodistot.suomi.fi/codelist-api/api/v1/integration/containers" -H "Content-Type: application/json" -H "Authorization: Bearer INSERT_TOKEN_HERE" |
...
| Code Block |
|---|
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 -rajapintaesimerkki (Tietomallit):
| Code Block |
|---|
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 rajapinta esimerkki-rajapintaesimerkki:
Tietomallit
| Code Block |
|---|
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
| Code Block |
|---|
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" |
...
| Code Block |
|---|
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 -rajapintaesimerkki (Tietomallit):
| Code Block |
|---|
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" |
...
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 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.
...
Tällä hetkellä resolvoinnissa tuetaan seuraavia alla olevassa taulukossa esitettyjä sovelluksia ja formaatteja.
...
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>
...