Transition from API version 11 to 12 (search and import API)
These instructions have been drawn up for organisations using the current search API (OUT API) and import API (IN API) of the Finnish Service Catalogue (FSC) and preparing to transfer from API version 11 to version 12.
The instructions support assessing the workload and starting to use the new version.
What is going to change compared to the previous version?
This version switchover differs from previous ones in scope: the changes are significant and require more preparation and development work from the parties implementing the integration.
Impact of the changes on API users
Required actions
- Use of API version 12 will require activating an API key. See the instructions on how to start using the API key.
- API users must update the logic of API calls and information processing to correspond to the new version's structure and response structures.
- New API calls and response structures must be carefully tested. Testing can be carried out in the customer test environment or, for the search API, in the production environment. More detailed testing instructions will be published later.
- Familiarise yourself with the API documentation in the customer test environment in ScalarOpens in a new window. as well as with the following summary of changes to the API.
Considerations for the transition period
During the transition period – i.e. for as long as version 11 is still available for updating data to the FSC – two versions of the FSC’s data content, version 11 and version 12, will run simultaneously in the background.
The transition phase progresses in phases in the following way in the customer test and production environments.
API version 12 in the customer test environment
- Data entry and updates will be done in version 11, from where the data is transferred in the background to the version 12 side with a delay lasting about 1–1.5 hours.
- The search API of version 12 is a beta version, so it may still undergo changes before the final version.
- The import API of version 12 will be published in the customer test environment in autumn 2026 (the schedule will be specified). The aim is to no longer make significant changes to the search API after this.
- A user interface compatible with version 12 will be published in the customer test environment (the schedule will be specified).
API version 12 in the production environment
- The search API of API version 12 is available (a beta version).
- Data entry and updates will be done through the current FSC user interface or API version 11, and the data is transferred in the background to the version 12 side with a delay lasting about 1-1.5 hours.
The transition period will continue until version 12 is fully implemented in production, and version 11 will be discontinued in April 2027 (date to be specified).
Changes to search APIs
There are two separate search methods in API version 12
- searching for an individual piece of content with an ID
- data retrieval with search criteria using the Search method and its parameters.
The Search method will have versatile filters that can be used to retrieve data from the API with different perspectives. The search can be narrowed by organisation, organisation type, service class, keyword, target group and regional information, for example. Several different search filters can be used to narrow the search, and several different values can be given in one search filter.
Content returned by the search API
- For data supplementing or classifying the searched content – such as service target groups, life events or keywords – only identifiers (IDs) are returned, not the entire data content.
- The search API will only return published data. Archived content (service channel, organisation, service) can only be search with separate calls. These calls will only return identifiers (IDs), not the whole content.
- Different language data of the same content is returned in its own collection in the languageVersions structure. The example below includes a part of the service fields that are available as different language versions. The example does not include all data returned by the API.
"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.",
},
...
Changes to import APIs
API version 12 offers
- Creation and update of published content
- Archiving of content
Content transmitted in the import API
The same principles are followed in the import API as in the content returned by the search API.
- For data supplementing or classifying the content that will be imported – such as the target groups, life events or keywords of the service – only identifiers (IDs) are returned, not the entire data content.
- Only published information is transmitted in the import API. Data archiving is carried out with separate calls.
- Different language data of the same content are transmitted in their own collections in the languageVersions structure.
Use of External id in the import API
Note for users of the External id of the source system:
- Version 12 supports externalId (the identifier of an external source system) only for POST APIs, the following content types: organisation, service and service channel.
- Version 12 will have an API that can be used to search for externalId-contentId correspondences related to the API in question by content type: organisations, services, service channels.
- If necessary, take advantage of the search in the correspondences table to get the contentId for the GET, PUT, and DELETE API calls.
- The exact implementation and calls of the API returning the correspondences of the IDs will be specified in more detail when the development work progresses.
Summary of the changes
The following more detailed summary of the changes in the APIs has been drawn up by comparing the APIs with API version 11Opens in a new window..
Please note that the version 12 API calls presented in the summary are indicative. Up-to-date and more detailed information is available in the FSC API Specification documentation of the customer test environment Opens in a new window.(training environment).