Siirtyminen rajapintaversiosta V11 versioon V12 (hakurajapinta)
Beta - sisältö on kesken
Tämä ohje on laadittu PTV:n hakurajapinnan (OUT-rajapinta) käyttäjäorganisaatioille, jotka hyödyntävät PTV-tietoja nykyisen OUT-rajapinnan kautta ja valmistautuvat siirtymään rajapintaversiosta 11 versioon 12. Ohje tukee työmäärän arviointia ja uuden version käyttöönoton toteuttamista. Tuontirajapinta-asiakkaille (IN-rajapinta) laaditaan myöhemmin erillinen ohje versionvaihdon tueksi.
Ohje on alustava, ja sen sisältöä täydennetään ja päivitetään kevään 2026 aikana PTV:n arkkitehtuuriuudistustyön edetessä. Merkintä "tulossa myöhemmin" tarkoittaa, että ohjeen sisältö täydentyy kevään 2026 aikana osana PTV:n arkkitehtuuriuudistusta.
Tämä versionvaihto poikkeaa aiemmista laajuudellaan: muutokset ovat merkittäviä ja vaativat enemmän valmistelua ja kehitystyötä integraation toteuttajilta.
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ä. Katso ohje [rajapinnan testauksesta] (tulossa myöhemmin).
Huomioi, että siirtymäaikana – eli aikana, kun 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. Tietojen syöttö ja päivitys tehdään edelleen versio 11 kautta, josta tiedot siirtyvät taustalla versio 12 puolelle n.1-1,5 tunnin viiveellä.
Ensimmäinen maaliskuussa 2026 julkaistava rajapintaversio on beta-versio, johon voi tulla vielä muutoksia ja tarkennuksia ennen lopullista versiota.
Kun PTV:n tietojen tuontirajapinnat tulevat testikäyttöön syksyllä 2026, hakurajapintojen sisältö pyritään vakiinnuttamaan. Tavoitteena on, että niihin ei enää tehtäisi merkittäviä muutoksia.
Hakurajapintojen muutokset
Rajapinnan versiossa V12 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.
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.", }, ...
Search haku tarjoaa hakufiltterit, joiden avulla rajapinnasta voidaan hakea tietoa eri näkökulmista. Hakufilttereitä ovat palvelu (tunniste) ja asiointikanava (tunniste).
Search haku tarjoaa monipuoliset hakufiltterit, joiden avulla rajapinnasta voidaan hakea tietoa eri näkökulmista. Hakufilttereitä ovat esimerkiksi pohjakuvaustyyppi, organisaatio ja palveluluokka.
V12 rajapinnat (GET) -arkistoitu sisältö
/api/v12/general-description/archived
Poistuvat V11 rajapinnat (GET) (näille ei vastaavaa rajapintaa versiossa V12)
Search haku tarjoaa monipuoliset hakufiltterit, joiden avulla rajapinnasta voidaan hakea tietoa eri näkökulmista. Hakufilttereitä ovat esimerkiksi aluetieto ja organisaatiotyyppi.
V12 rajapinnat (GET) -arkistoitu sisältö
/api/v12/organization/archived
Poistuvat V11 rajapinnat (GET) (näille ei vastaavaa rajapintaa versiossa V12)
Search haku tarjoaa monipuoliset hakufiltterit, joiden avulla rajapinnasta voidaan hakea tietoa eri näkökulmista. Hakufilttereitä ovat esimerkiksi toimialaluokka, palveluluokka, asiasana, kohderyhmä ja organisaatio.
Huomioi, että palvelun pohjakuvauksen tiedot eivät sisälly palvelun tietojen palautukseen. Palvelun tiedoissa palautuu ainostaan käytetyn pohjakuvauksen tunniste (id), ei sen sisältöä.
V12 rajapinnat (GET) -arkistoitu sisältö
/api/v12/service/archived
Poistuvat V11 rajapinnat (GET) (näille ei vastaavaa rajapintaa versiossa V12)
/api/v11/Service/serviceWithGD/{id}
/api/v11/Service/list
/api/v11/Service/archived/list
/api/v11/Service/serviceWithGD/list
/api/v11/Service/active
/api/v11/Service/active/{id}
/api/v11/Service/serviceChannel/{serviceChannelId} (käytä tämän tilalla jatkossa Service Channel -hakurajapintaa)
Huomaa, että alla esitetyt V12‑rajapintakutsut ovat suuntaa antavia. Ajantasaiset ja tarkemmat tiedot löytyvät asiakastestiympäristön (koulutusympäristö) PTV API Specification ‑dokumentaation kohdasta Service channel. (linkki tulossa myöhemmin)
V12-versiossa toteutetaan seuraavat haut
V12 rajapinnat (GET)
/api/v12/service-channel/content-id/{contentId}
/api/v12/service-channel/external-id/{externalId}
/api/v12/service-channel/search
Search haku tarjoaa monipuoliset hakufiltterit, joiden avulla rajapinnasta voidaan hakea tietoa eri näkökulmista. Hakufilttereitä ovat esimerkiksi aluetieto, organisaatio ja asiointikanavan tyyppi.
V12 rajapinnat (GET) -arkistoitu sisältö
/api/v12/service-channel/archived
Poistuvat V11 rajapinnat (GET) (näille ei ole vastaavaa rajapintaa versiossa V12)
Search haku tarjoaa hakufiltterit, joiden avulla rajapinnasta voidaan hakea tietoa eri näkökulmista. Hakufiltterinä esimerkiksi organisaation mukaan rajaaminen.
