How to: Use an External API in a Multi-Select Dropdown Component

Overview

In Unqork, you can use External APIs in Multi-Select Dropdown and regular Dropdown components. A Multi-Select Dropdown or Dropdown component is one of the best ways to present a long list of selectable options to your end-user. But, populating lists can be tedious and time-consuming, and if more than one component uses the same list, it must be maintained in multiple places. The Dropdown and Multi-Select components let you retrieve data from a source outside your module. Use these components to set up an external API call to populate your list.

As with any external API call, it’s important to refer to the provider's API documentation. The API must be a table array of JSON objects for the Dropdown or Multi-Select Dropdown components to populate the values correctly.

Look at the following external API as an example: https://api.thedogapi.com/v1/breeds. Clicking the link opens the API response that contains a JSON object with dog breed data. You might want to use only one piece of that information in a Dropdown or Multi-Select Dropdown component. In this how-to guide, you'll create a drop-down that lists only the dog breed names.

Here's how the completed use case looks in Express View:

Here's how the completed use case looks in the Module Builder:

How to Make an External API Call in a Multi-Select Dropdown Component

Making external API calls in a Multi-Select Dropdown component is a two-part process. First, the external API service is set up on the Services Administration page. Next, a Multi-Select Dropdown uses the external API service.

What You Need

To set up this use case, you need:

Pre-Configuration

Configure the External Service

First, you must add the Dog API external service to Services Administration.

If you are completing this lab in the Training environment, the Dog API is likely already set up. Double-check the list of Active Services before completing this step. If the Dog API is on the list of Active Services, move to the Configure the Multi-Select Dropdown Component section.

To add the Dog API external service to Services Administration:

At the top right of the Unqork Designer Platform, click Settings.
Select Administration
Under Integration, click Services Administration.
Click + Add a Service. The Create New Service modal displays.
In the Service Title field, enter Dog API.
In the Service Name field, enter dog-API.
Click Create. The Dog API Service page displays.
Click Edit.
From the Service menu, click Service Type.
In the Service Protocol + Host field, enter https://api.thedogapi.com/v1/.
From the Authentication method* drop-down, select No Authentication.
Click Save Changes.

Configuration

Configure the Multi-Select Dropdown Component

Next, add a Multi-Select Dropdown component to list options for the end-user. The external Dog API populates the component.

These instructions assume that you have an open module saved with a title.

In the Module Builder, drag and drop a Multi-Select Dropdown component onto your canvas.
In the Property ID field, enter dogBreeds.
In the Label Text field, enter Dog Breeds.
In the Item Template field, enter <span>{{ item.name }}</span>. This sets the HTML display for each item.
From the component's configuration window, select Data.
From the Data Source Type, select URL.
From the Service drop-down, select Dog API.
In the Data Source URL, enter breeds.
In the Value Property field, enter name. The Value Property setting maps the name value in the JSON Object from the API response to the Multi-Select Dropdown selections.
Click Save & Close.
Save your module.

Here's how the completed how-to guide looks in Express View: