Configuring additional features and settings for API Gateway data service

You can configure additional features for API Gateway data service to customize settings.

Reusing output from an earlier transaction

Later transactions can use output from earlier transactions. This behavior is useful when an API returns an identifier, token, status value, or result reference that another API call needs as input.

Open the later transaction and go to the Input tab.
Find the input field to map.
In the Source arrow, select the earlier transaction.
In the Source field arrow, select the output field to use.
Click Save.

Adding a custom output

In most cases, the API metadata includes output fields. In the case it doesn’t you can add output fields manually.

Open the later transaction and go to the Input tab.
Click the + Add custom output button.
Specify the response path in Field path.
Specify a name in Description.
Click Add.
Repeat for each custom output field.
Click Save.

Configuring polling

Use polling when the selected API is asynchronous. Repeat the request until a specific value appears in the response or a field reaches the required state.

Edit the transaction that must poll.
Click the Polling tab, and specify these fields:

Interval (ms)

Frequency of the transaction to run while polling. This is represented by a whole number with a minimum of 1000.

Timeout (ms)

Length of time that polling can continue before it fails. This is represented by a whole number which is greater than the interval.

Condition field path

The response field to evaluate. Use dot notation, for example, status or result.state.

Operator

Method for evaluating the field. These are Equals, Not equals, Contains, or Exists.

Expected value

The value where we compare the condition.
Click Save.

Using the Test Transaction

When configuring a transaction, you can use the Test Transactiontab to test the transaction directly in the editor. Testing the transaction in the editor helps you validate the configuration, check required inputs, and identify response fields to include in the output.

Edit a transaction and click the Test transaction
Specify the values for the available input fields.
Click Run.
Review the returned response. If needed, add fields form the response as custom outputs.

On success, the panel shows the response as formatted JSON. On failure, the panel shows the returned status code and error message.

Configuring error mapping

Use error mapping to extract meaningful error details from an API response and display them to the user when a transaction fails. Without error mapping, the system shows a generic error message. With error mapping configured, the error dialog can display the specific title, message, and error code returned by the API.

The Error mapping tab is available on API Gateway transactions only.

Edit a transaction and click the Error mapping tab.
Specify these fields as needed:

Error title path

JSONPath to the error title in the response, or static text. Falls back to the data service name if not set. This is displayed in error dialog title.

Error message path

JSONPath to the error message in the response. This is displayed in main text in the error dialog.

Error code path

JSONPath to the error code in the response, or static text. This is displayed below the error message in the error dialog.
Click Save.

JSONpath examples:

errors[0].desc : first item in an errors array.
error.message : nested field.
title : top-level field.

Retrieving data from Data Fabric

To retrieve data from Data Fabric, configure three transactions in one API Gateway data service. Follow the same transaction setup process described earlier, but use the values for Data Fabric.

Submitting the Data Fabric job

This is the an example of the first transaction, submitting the Data Fabric job.

Add a transaction and specify the information in their respective tabs and fields:

Name

For example, Jobs.

API Suite

This is on the Properties tab. For example, DATAFABRIC.

Path

This is on the Properties tab. For example, /jobs/.

Response code

This is on the Properties tab. For example, 202.

Exclude transaction data from output

This is on the Properties tab. This field is selected. This keeps intermediate data out of the final result.

body

This is on the Input tab. This is the SQL statement to execute, for example, SELECT * FROM OOHEAD. This points to which data to retrieve.

queryID

This is on the Ouput tab. This is the SQL statement to execute, for example, SELECT * FROM OOHEAD. Ensure that queryId is available as an output. Later transactions require this value to check the job status and retrieve the result.
To verify the transaction and obtain a queryId for testing the next steps, select the Test Transaction tab and specify these fields:

SQL statement

Use the same SQL statement as specified in the body field under the Input.

Maximum number of records

This is optional. Leave blank or specify any number.
Click Run.
In the response section, copy the returned queryId, for example hHrL8BTBwgtLGpzkXr66h. Use this value when you test the next two transactions in Test Transaction.

Polling the job status

Add a second transaction.

Configure these fields under their respective tabs:

Name

For example, Jobs_Status.

API Suite

This is on the Properties tab. For example, DATAFABRIC.

Path

This is on the Properties tab. For example, /jobs/{queryId}/status/.

Response code

This is on the Properties tab. For example, 201.

Exclude transaction data from output

This is on the Properties tab. This field is selected. This keeps intermediate data out of the final result.

queryId

This is on the Input tab. For example, the source is jobs. Source field is queryId.

Polling interval (ms)

This is on the Polling tab. For example, 5000.

Polling timeout (ms)

This is on the Polling tab. For example, 20000

Conditional field path

This is on the Polling tab. For example, status.

Operator

This is on the Polling tab. For example, Equals.

Expected value

This is on the Polling tab. For example, FINISHED.
To verify the transaction, navigate to the Test Transaction tab and paste the queryId copied from first Transaction into the unique queryId field.
Click Run and confirm that the response shows the status of FINISHED.

Retrieving the job result

Add a third transaction.

Configure these fields under their respective tabs:

Name

For example, Jobs_results.

API Suite

This is on the Properties tab. For example, DATAFABRIC.

Path

This is on the Properties tab. For example, /jobs/{queryId}/results/.

Response code

This is on the Properties tab. For example, 200.

queryId

This is on the Input tab. For example, the source is Jobs_status. Source field is queryId.

limit

This is on the Input tab. For example, 100.
To verify the transaction and select output fields, navigate to the Test Transaction tab and
Specify these fields:

The unique queryId

Paste the queryId copied from the previous transactions.

Limit

Specify the maximum number of records to return, for example 100.
Click Run.
In the Response section, click Extract fields button, then click Add as output for each field included.
Navigate to the Output tab and confirm that the fields were added.
Save the data service, and then save the application.

Use the API gateway data service

When the data service runs, transactions run in their configured order. For a standard data service, each transaction runs once and passes configured outputs to later transactions as needed.

For an asynchronous data service, such as when the service retrieves data from Data Fabric, a polling transaction runs immediately the first time, evaluates the stop condition, and then continues at the configured interval until the condition is met or the timeout is reached.

If the stop condition is satisfied, the last successful response becomes the output used by later transactions. If the timeout is reached, the transaction fails and later transactions do not run.