TABLE OF CONTENTS

• Step 1: Creating a Data Source 
• Step 2: Configuring a Data Set
• Step 3: Configuring Components
• Step 4: Making a Query and Viewing Results

When your application needs to interact with an external API endpoint from another system, configuring an External Data Source is essential. An External Data Source provides your app with the necessary definitions to use the API, and the CafeX platform handles connection establishment, security, and authentication. Additionally, it can supply your application with a schema for the API endpoint you are using.

In this article, we'll guide you through the process of configuring a simple application with a search box that queries an API and presents the results. We'll cover the following steps:

1. Creating a data source
2. Configuring a data set
3. Configuring components
4. Making a query and viewing results

Before proceeding, ensure that the app and workspace have been created. If you haven't set them up yet, please refer to the following instructions: Adding a new App and Setting up a Workspace.

Step 1: Creating a Data Source 

First, you will set up a data source that connects to the API you will be querying. This involves defining the API endpoint and configuring the schema that the app will use to understand the data.

To create a data source:

1. Navigate to the App Studio. In the App Studio, click the External data sources icon () in the Side Menu to open the External data sources page.
2. Click Add new data source.
3. In the Data Source pop-up, specify the Name, Group, and select recommended Configuration version for the data source.
4. Under Request > Configuration, specify a JSON definition for the endpoint that your App uses to access the API.
5. Under Response > Schema, there is a JSON definition of the information your App uses. Click Extract Schema and enter values for the REST API inputs to have CafeX call the endpoint and parse the data object.
6. Click Send Request. The response schema provides the App Studio with a definition of response objects that your App references. If necessary, you can manually update the schema.
7. Click Accept to accept the schema.
8. Click Update to update the data source.
9. A newly added data source appears in the list.
    

Step 2: Configuring a Data Set

In this step, you will create a data set that utilizes the previously defined data source. This data set will handle the API queries and manage the data flow within your application.

To configure a data set:

1. Click the Design editor icon ().
2. On the Appearance and Configuration panel, click Configuration.
3. Click Add Data set.
4. Specify the Name of the data set, its Type (External API), and then select the data source you have created in step 1 from the drop-down menu.
5. The Evaluate automatically toggle becomes active. Select the Source of the Input and Requirement. Ensure that a value is specified for the Source in the data set configuration, as the data set evaluates when there’s a value specified for the Source.
6. Click Add. The newly added data set appears in the Configuration panel.

Step 3: Configuring Components

In this step, you will add and configure the necessary components for your application, such as a search box and a results display table. These components will interact with the data set to enable the search functionality and display the results.

First, we are going to add the Form component to submit values, which will be used to initiate a search.

1. Click Components on the Explorer and Components panel. 
2. Under Data, select the Form component and drag it onto the canvas.
3. Click on the new Form component.
4. Update the name of the newly added component.
5. In the Appearance and Configuration section, click Configuration.
6. Set the Search form toggle to ON (Toggle to blue).
7. In the list of configurations, locate the Data set drop-down list and select the data set you created in Step 3 to wire the component to the data set. The form will pull in the URL parameter that will be used to do the search automatically.

Next, we are going to add the Table component to present rows of data,

1. Select the component under the Data category, for example Table, and drag it onto the canvas. Note: If you expect the results to be an array of records, use components like Table or Card. Other components, such as Form, can view only a single record.
2. Click on the new Table component.
3. Update the name of the newly added component.
4. In the Appearance and Configuration section, click Configuration.
5. Set the Read only toggle to ON (Toggle to blue).
6. In the list of configurations, locate the Data set drop-down list and select the data set you created in Step 3 to wire the component to the data set.
7. Optionally, specify the Data path, that is a child object from the Data Set output to display on the table. If not specified, the top level parent is used.

Note: The data you see in the table in App Studio is 'mock' data and not fetched from the actual endpoint. You will see the real data when we move on to making a query in the next step.

Step 4: Making a Query and Viewing Results

In this step, you will test the application by making a query through the search box to ensure that it correctly queries the API and displays the results.

1. Navigate to the workspace inside the app. Open the app.
2. Enter a search term into the search box and click Search.
3. View the results in the designated component. In our case, it’s a Table.
    

If the results are displayed as expected, your application is successfully set up to query the API and present the data. If not, review the previous steps to ensure all configurations are correct.

You have now successfully built a simple application with a search box that queries an API and presents the results. This guide covered making a data source, configuring a data set, adding and configuring components, and making a query to see the results. Check out other articles to learn how you can add more features and improve your application's functionality.