How To: Create a Variable Endpoint for an Integration Gateway Recipe

Overview

The Integration Gateway supports variable path parameters for endpoints. Variable path parameters let you insert a dynamic value into an endpoint's An API endpoint is the location where an API receives requests for a specific resource on its server. It's the point of contact between an API client and an API server, and is usually a uniform resource locator (URL) that provides the location of the resource. pathway. For example, if you create an Unqork Connector that retrieves a module's submission data, you can create an endpoint with a variable parameter that uses the module's ID in the pathway.

Variable path parameters let you create endpoints similar to Unqork's API. For example, the Unqork Get Module Submissions API endpoint looks like the following: https://{host}/api/1.0/modules/{moduleId}/submissions. The {host} and {moduleId} values are variables that you replace to target a specific environment and module.

Create a Variable Endpoint for an Existing Recipe

For this example, you'll create and connect a variable endpoint to an existing recipe. Later, we'll set up a module with a Plug-In component that targets the variable endpoint.

What You Need

Creating the Variable Endpoint

First, use the Integration Gateway to create a new endpoint for an existing recipe. These instructions assume you have an existing recipe where you'll create an endpoint.

For this example, we'll use the Integration Gateway recipe set up in the How to: Retrieve a Payload Using an Unqork Connector article.

To create a new variable endpoint:

1. At the top right of the Unqork Designer Platform, click Settings ▾.
2. Select Administration.
3. Under Integration, click API Access Management.
4. Select the API Platform tab.

A static image displaying the Integration Gateway platform tab.

5. Select your API Collection.
6. Click + New Endpoint.
7. From the Recipe* drop-down, select an existing recipe.

For this example, we'll use the Unqork Get Module Submissions recipe created in the How to: Retrieve a Payload Using an Unqork Connector article.

8. From the HTTP Method* drop-down, select the request method for the recipe. For the Get Module Submissions endpoint, select GET.
9. In the Endpoint Name* field, enter a unique name. This value displays in a Plug-In component as an External Service.

Configuring the Variable Endpoint Path

The Endpoint Path field accepts variable parameters. To create a variable parameter, use a single set of curly braces {} to enclose a variable value. For this example, the Unqork Get Module Submissions recipe uses the variable value moduleId to retrieve submissions from the specified module. Adding {moduleId} to the endpoint path displays the recipe's moduleId value when calling the endpoint.

1. In the Endpoint Path*, enter a value that includes a variable parameter. For example enablement/{moduleId}/getModuleSubmissions.

A static image displaying the Add New Endpoint modal. the Endpoint path contains a variable parameter.

2. Click Add Endpoint.
3. On the endpoint tile, click the ··· (options) button.
4. Select Activate Endpoint. The endpoint's status changes from Never Active to Active.

Your variable endpoint is now active for you to select it in a Plug-In component.

Configuration

The last step of the process is to configure a module to retrieve Unqork application data using the variable endpoint. These instructions assume you have a module saved with a title.

For this example, we'll use the Integration Gateway recipe set up in the How to: Retrieve a Payload Using an Unqork Connector article.

Configure the Text Field Component

Configure a Text Field component for entering the module ID. This value inputs into the Plug-In component you'll configure in the next step.

1. In the Module Builder, drag and drop a  Text Field component onto the canvas.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter textModuleId.
3. In the Canvas Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Module ID:.
4. Click Save & Close.

Configure the Plug-In Component

Add a Plug-In component to use your new Integration Gateway endpoint and retrieve your workspace application.

1. Drag and drop a Plug-In component onto your canvas, placing it below the textModuleId  Text Field component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. and Canvas Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. fields, enter plugGetModuleSubmissions.
3. Set the Service Type to External.
4. From the External Services drop-down, select the endpoint you created.

In the Data Source URL field, the variable parameter from the Configuring the Variable Endpoint Path section now displays in {{}} (double curly brackets).

A static image displaying the Plug-In component's configuration window with the selected Get Module Submissions by eye dees endpoint.

5. In the Data Source URL field, modify the variable value to use the module's textModuleId  Text Field component value. For example, {{moduleId}} becomes {{data.textModuleId}}. Now, when users enter a value in the textModuleId  Text Field component field, the Data Source URL updates the value between the brackets.
6. In the INPUTS table, enter the following:
Property ID Mapping

textModuleId

moduleId
7. Click Save.

Configure the Button Component

Next, add a Button component to trigger the Plug-In component.

1. Drag and drop a Button component Icon Button component onto the canvas, placing it below your Plug-In component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter btnGetModuleSubmissions.
3. In the Canvas Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Get Module Submissions.
4. Set the Action Type to Event.
5. In the Trigger field, enter plugGetModuleSubmissions.
6. Click Save & Close.
7. Save your module.

View the API Request Payload in the DevTools Console

Now that you've built your endpoint and created a module that can call it, verify the endpoint works correctly.

1. Preview your module in Express View Express View is how your end-user views you application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View..
2. Right-click anywhere in Express View and click Inspect. The DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software. displays.

Your browser type and settings might look different than the image and steps displayed below.

3. From the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software., select the Network tab.
4. In the Module ID field, enter a module ID that contains submission data.
5. Click the Get Module Submissions button. The execute request displays in the Network tab's list.
6. Select the execute request, then click Payload. The Request Payload data displays.

In the Request Payload, the endpoint URL replaces the Plug-In component {{data.textModuleId}} variable parameter with the value from the textModuleId  Text Field component field.

A static image displaying the DevTools network tab. The API Request is selected the the Payload displays the variable endpoint.

The endpoint URL updates every time you call the endpoint using a different module ID.

Resources