Siirtyminen rajapintaversiosta 11 versioon 12 (haku- ja tuontirajapinta)
Beta - sisältö on keskenTämä ohje on laadittu Palvelutietovarannon (PTV) nykyisen hakurajapinnan (OUT-rajapinta) ja tuontirajapinnan (IN-rajapinta) käyttäjäorganisaatioille, jotka valmistautuvat siirtymään rajapintaversiosta 11 versioon 12.
Ohje tukee työmäärän arviointia ja uuden version käyttöönoton toteuttamista.
Mikä muuttuu edelliseen versioon verrattuna?
Tämä versionvaihto poikkeaa aiemmista laajuudellaan: muutokset ovat merkittäviä ja vaativat enemmän valmistelua ja kehitystyötä integraation toteuttajilta.
Muutosten vaikutukset rajapinnan käyttäjille
Tarvittavat toimenpiteet
- Rajapintaversion 12 käyttö edellyttää API-avaimen käyttöönottoa. Katso ohje API-avaimen käyttöönotosta.
- Rajapinnan käyttäjän tulee päivittää rajapintakutsujen logiikka ja tietojen käsittely vastaamaan uuden version rakennetta ja vastausrakenteita.
- Uudet rajapintakutsut ja vastausrakenteet on testattava huolellisesti. Testauksen voi tehdä asiakastestiympäristössä tai hakurajapinnan osalta tuotantoympäristössä. Tarkempi testausohje julkaistaan myöhemmin.
- Tutustu asiakastestiympäristön rajapintadokumentaatioon ScalarissaAvautuu uuteen ikkunaan. sekä alla olevaan koosteeseen rajapintamuutoksista.
Siirtymäaikana huomioitavaa
Siirtymäaikana – eli niin kauan kuin rajapintaversio 11 on yhä käytettävissä tietojen päivittämiseen PTV:hen – taustalla toimii samanaikaisesti kaksi versiota PTV:n tietosisällöstä: versio 11 ja versio 12.
Siirtymävaihe etenee vaiheittain seuraavasti asiakastesti- ja tuotantoympäristöissä.
Rajapintaversio 12 asiakastestiympäristössä
- Tietojen syöttö ja päivitys tehdään version 11 kautta, josta tiedot siirtyvät taustalla version 12 puolelle n.1-1,5 tunnin viiveellä.
- Version 12 hakurajapinta on beta-versio, johon voi tulla vielä muutoksia ennen lopullista versiota.
- Version 12 tuontirajapinta julkaistaan asiakastestiympäristöön syksyllä 2026 (aikataulu tarkentuu). Tavoitteena on, että tämän jälkeen hakurajapintaan ei enää tehdä merkittäviä muutoksia.
- Version 12 mukainen käyttöliittymä julkaistaan asiakastestiympäristöön (aikataulu tarkentuu)
Rajapintaversio 12 tuotantoympäristössä
- Rajapintaversion 12 hakurajapinta on käytettävissä (betaversio).
- Tietojen syöttö ja päivitys tehdään nykyisen PTV:n käyttöliittymän tai rajapintaversion 11 kautta ja tiedot siirtyvät taustalla version 12 puolelle n. 1–1,5 tunnin viiveellä.
Siirtymäaika jatkuu, kunnes versio 12 otetaan kokonaisuudessaan käyttöön tuotannossa ja versio 11 poistuu käytöstä huhtikuussa 2027 (tarkentuu).
Hakurajapintojen muutokset
Rajapintaversiossa 12 on kaksi erilaista hakutapaa
- yksittäisen sisällön haku tunnisteella
- tietojen haku hakuehdoilla, jolloin käytetään Search-metodia ja sen hakuparametreja.
Search-metodi tarjoaa monipuoliset hakufiltterit, joiden avulla rajapinnasta voidaan hakea tietoa eri näkökulmista. Hakua voidaan rajata muun muassa organisaation, organisaatiotyypin, palveluluokan, asiasanan, kohderyhmän ja aluetiedon perusteella. Hakua voi rajata usealla eri hakufiltterillä ja yhdessä hakufiltterissä voidaan antaa useita eri arvoja.
Hakurajapinnan palauttama sisältö
- Haettua sisältöä täydentävistä tai luokittelevista tiedoista – kuten palvelun kohderyhmät, elämäntilanteet tai asiasanat – palautetaan vain tunnisteet (ID:t), ei koko tietosisältöä.
- Hakurajapinta palauttaa vain julkaistut tiedot. Arkistoitua sisältöä (asiointikanava, organisaatio, palvelu) voidaan hakea erillisillä kutsuilla. Nämä kutsut palauttavat ainoastaan tunnisteet (ID:t), eivät koko tietosisältöä.
- Saman sisällön erikieliset tiedot palautuvat omassa kokoelmassaan languageVersions-rakenteessa. Alla olevaan esimerkkiin on otettu osa palvelun kentistä, joille on saatavilla eri kieliversioita. Esimerkki ei sisällä kaikkia rajapinnan palauttamia tietoja.
"languageVersions": {
"fi": {
"name":"Osallistuva budjetointi",
"alternativeName": "Osbu",
"summary": "Tee ehdotuksia ja äänestä – ole mukana kunnan päätöksenteossa koskien taloutta ja resursseja.",
"description": "Mitä palvelua tai asiaa kaipaat porvoolaisten iloksi ja hyödyksi? Ehdota ideaa ja äänestä suosikkiasi Porvoon kaupungin toteutettavaksi.",
},
"sv": {
"name": "Deltagande budgetering",
"alternativeName": "Osbu",
"summary": "Lämna förslag och rösta – delta i stadens beslutsfattande om ekonomi och resurser.",
"description": "Vilken tjänst eller sak längtar du efter som kan vara till glädje och nytta för invånare i Borgå? Föreslå en idé och rösta din favorit att förverkligas i Borgå stad.",
},
...
Tuontirajapintojen muutokset
Rajapintaversio 12 tarjoaa
- Julkaistun sisällön luonnin ja päivityksen
- Sisällön arkistoinnin
Tuontirajapinnassa välitettävä tietosisältö
Tuontirajapinnassa noudatetaan samoja periaatteita kuin hakurajapinnan palauttamassa sisällössä.
- Tuotavaa sisältöä täydentävistä tai luokittelevista tiedoista – kuten palvelun kohderyhmät, elämäntilanteet tai asiasanat – välitetään vain tunnisteet (ID:t).
- Tuontirajapinnassa välitetään vain julkaistua tietoa. Tietojen arkistointi tehdään erillisillä kutsuilla.
- Saman sisällön erikieliset tiedot välitetään languageVersions-rakenteessa omissa kokoelmissaan.
ExternalId-tunnuksen käyttö tuontirajapinnassa
Huomioitavaa lähdejärjestelmän externalId-tunnuksen käyttäjille:
- Versio 12 tukee externalId-tunnusta (ulkoisen lähdejärjestelmän tunnus) ainoastaan POST-rajapinnoille, seuraaville sisältötyypeille: organisaatio, palvelu ja asiointikanava.
- Versioon 12 on tulossa rajapinta, jolla voi hakea kyseiseen API-tunnukseen liittyvät externalId-contentId –vastaavuudet sisältötyypeittäin: organisaatiot, palvelut, asiointikanavat.
- Hyödynnä vastaavuudet -taulukon hakua tarvittaessa, jotta saat contentId:n GET, PUT ja DELETE-rajapintakutsuja varten.
- Tunnusten vastaavuudet palauttavan rajapinnan tarkka toteutus ja kutsut tarkentuvat kehitystyön edetessä.
Kooste muutoksista
Seuraava tarkempi kooste rajapintojen muutoksista on tehty peilaten rajapintaversioon 11Avautuu uuteen ikkunaan..
Huomaa, että koosteessa esitellyt version 12 rajapintakutsut ovat suuntaa-antavia. Ajantasaiset ja tarkemmat tiedot löytyvät asiakastestiympäristön (koulutusympäristö) PTV API Specification dokumentaatiostaAvautuu uuteen ikkunaan..