Övergång från gränssnittsversion 11 till version 12 (sök- och importgränssnitt)
Denna anvisning har utarbetats för organisationer som använder Servicedatalagrets (SDL) nuvarande sökgränssnitt (OUT-gränssnitt) och importgränssnitt (IN-gränssnitt) och som förbereder sig på att övergå från gränssnittsversion 11 till version 12.
Anvisningen stöder bedömningen av arbetsmängden och genomförandet av ibruktagandet av den nya versionen.
Vad kommer att förändras jämfört med föregående version?
Detta versionsbyte avviker från tidigare i fråga om omfattning: ändringarna är betydande och kräver mer beredning och utvecklingsarbete av dem som genomför integrationen.
Hur ändringarna påverkar användarna av gränssnittet
Nödvändiga åtgärder
- Användningen av gränssnittsversion 12 förutsätter aktivering av en API-nyckel. Se anvisningen om aktivering av API-nyckeln.
- Användaren av gränssnittet ska uppdatera logiken i gränssnittsanropen och behandlingen av information så att de motsvarar den nya versionens struktur och svarsstrukturer.
- Nya gränssnittsanrop och svarsstrukturer ska testas noggrant. Testningen kan göras i kundtestmiljön eller, när det gäller sökgränssnittet, i produktionsmiljön. En mer detaljerad testanvisning publiceras senare.
- Bekanta dig med kundtestmiljöns gränssnittsdokumentationÖppnas i ett nytt fönster. i Scalar samt sammanställningen av gränssnittsändringarna nedan.
Att beakta under övergångsperioden
Under övergångsperioden, det vill säga så länge gränssnittsversion 11 fortfarande kan användas för att uppdatera uppgifter i SDL, finns två versioner av SDL datainnehåll parallellt i bakgrunden: version 11 och version 12.
Övergångsfasen framskrider stegvis på följande sätt i kundtest- och produktionsmiljöerna.
Gränssnittsversion 12 i kundtestmiljön
- Inmatning och uppdatering av uppgifter görs via version 11. Därifrån överförs uppgifterna i bakgrunden till version 12 med en fördröjning på cirka 1–1,5 timmar.
- Sökgränssnittet för version 12 är en betaversion som ännu kan ändras före den slutliga versionen.
- Importgränssnittet för version 12 publiceras i kundtestmiljön hösten 2026 (tidtabellen preciseras senare). Målet är att inga betydande ändringar görs i sökgränssnittet efter detta.
- Användargränssnittet enligt version 12 publiceras i kundtestmiljön (tidtabellen preciseras senare).
Gränssnittsversion 12 i produktionsmiljön
- Sökgränssnittet för gränssnittsversion 12 är tillgängligt (betaversion).
- Inmatning och uppdatering av uppgifter görs via det nuvarande användargränssnittet för SDL eller via gränssnittsversion 11. Uppgifterna överförs i bakgrunden till version 12 med en fördröjning på cirka 1–1,5 timmar.
Övergångsperioden fortsätter tills version 12 tas i bruk i sin helhet i produktionen och version 11 tas ur bruk i april 2027 (tidpunkten preciseras senare).
Ändringar i sökgränssnitten
Det finns två olika söksätt i gränssnittsversion 12:
- sökning av ett enskilt innehåll med identifierare
- sökning av uppgifter med sökvillkor. Då används Search-metoden och dess sökparametrar.
Search-metoden erbjuder mångsidiga sökfilter. Med hjälp av dem kan information sökas i gränssnittet ur olika perspektiv. Sökningen kan avgränsas bland annat utifrån organisation, organisationstyp, servicegrupp, ämnesord, målgrupp och områdesuppgifter. Sökningen kan avgränsas med flera olika sökfilter. I ett och samma sökfilter kan flera olika värden anges.
Innehåll som sökgränssnittet returnerar
- För uppgifter som kompletterar eller klassificerar det sökta innehållet, såsom tjänstens målgrupper, livssituationer eller ämnesord, returneras endast identifierare (ID:n), inte hela innehållet.
- Sökgränssnittet returnerar endast publicerade uppgifter. Arkiverat innehåll (servicekanal, organisation, tjänst) kan sökas med separata anrop. Dessa anrop returnerar endast identifierare (ID:n), inte hela innehållet.
- Information på olika språk med samma innehåll returneras i en egen samling i languageVersions-strukturen. I exemplet nedan visas en del av de fält i tjänsten som finns på olika språk. Exemplet innehåller inte alla uppgifter som gränssnittet returnerar.
"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.",
},
...
Ändringar i importgränssnitten
Gränssnittsversion 12 erbjuder
- Skapande och uppdatering av publicerat innehåll
- Arkivering av innehåll
Datainnehåll som förmedlas i importgränssnittet
I importgränssnittet följs samma principer som för det innehåll som sökgränssnittet returnerar.
- För uppgifter som kompletterar eller klassificerar det innehåll som importeras, såsom tjänstens målgrupper, livssituationer eller ämnesord, förmedlas endast identifierare (ID).
- I importgränssnittet förmedlas endast publicerade uppgifter. Arkivering av uppgifter görs med separata anrop.
- Information på olika språk med samma innehåll förmedlas i egna samlingar i languageVersions-strukturen.
Användning av externalId-identifieraren i importgränssnittet
Att beakta för dem som använder externalId-identifieraren i källsystemet:
- Version 12 stöder externalId-identifieraren, det vill säga identifieraren i ett externt källsystem, endast i POST-gränssnitt för följande innehållstyper: organisation, tjänst och servicekanal.
- Till version 12 kommer ett gränssnitt där du kan söka motsvarigheterna externalId–contentId för den aktuella API-nyckeln enligt innehållstyp: organisationer, tjänster och servicekanaler.
- Använd vid behov sökningen i tabellen med motsvarigheter för att få contentId för gränssnittsanropen GET, PUT och DELETE.
- Den exakta implementeringen av och anropen till det gränssnitt som returnerar motsvarigheterna mellan identifierare preciseras i takt med att utvecklingsarbetet framskrider.
Sammanställning av ändringarna
Följande mer detaljerade sammanställning av ändringarna i gränssnitten har gjorts i jämförelse med gränssnittsversion 11Öppnas i ett nytt fönster..
Observera att gränssnittsanropen i version 12 som presenteras i sammanställningen är riktgivande. Uppdaterade och mer detaljerade uppgifter finns i dokumentationen PTV API Specification för kundtestmiljön (utbildningsmiljön)Öppnas i ett nytt fönster..