Integratie van Referentielijsten API

[joeridiederen]

Thema / Theme

Frontend

Omschrijving / Description

This RFC proposes integrating a Referentielijsten API into Open Forms to dynamically populate single-selection (keuzelijst) and multi-selection (selectievakjes) components with values retrieved from external reference lists.

Each time a form is loaded, Open Forms will fetch data from a configured Referentielijsten API endpoint. The fetched list populates selectable options, either as a single-choice dropdown or a multiple-choice checkbox group, depending on the component’s configuration.

The base URL and authentication of the Referentielijsten API is managed within the Open Forms administration interface. However, within each keuzelijst or selectievakjes-component’s settings, an administrator can specify a particular “code” (table identifier) to retrieve data for that specific table. This ensures that different components within the same form can request different sets of reference data from the same base URL, simply by varying the tabelcode. Also the isGeldig boolean should be visible for adminstrators.

As a “nice to have,” it would be beneficial if the component’s configuration UI could immediately display a preview of the retrieved data, providing visual confirmation that the correct tabelcode and parameters have been configured

For the keuzelijst (single selection), the user’s chosen label is stored as a string:

{
  "mijnKeuze": "Gekozen label"
}

For the selectievakjes (multiple selection), the chosen labels are stored as an array:

{
  "mijnSelecties": ["Label 1", "Label 2"]
}

Added value / Toegevoegde waarde

Integrating the Referentielijsten API to populate keuzelijst and selectievakjes components provides significant benefits. By seamlessly fetching and displaying dynamically maintained reference data, administrators no longer need to manually update static lists. This ensures that forms remain accurate and current over time, especially when tied to official, centrally managed reference lists.

Aanvullende opmerkingen / Additional context

• The keuzelijst must support searching, as all options will be loaded at once.

• If the API is unavailable or returns an error, Open Forms must display a user-friendly error message to the end user.

Nice to have: the integration must be language-aware*: if the form is presented in a certain language (e.g., Dutch, English), Open Forms should add a query parameter or header to the API call to retrieve language-appropriate labels.

*Not yet possible in the Referentielijsten API, request scheduled for further discussion.