REST Data Source Connector

The REST Data Source Connector allows you to pull data from an external API into a data source, populating its rows/columns for use in screens.

This connector functions similarly to our REST Field (in-app REST requests) that can push or pull data from your API, or a custom API.

However, getting the data into the correct format generally requires a few changes to be made to the data's structure before it could be of use in-app or our web portal, either by coding this yourself or utilizing a 3rd party service (i.e., Zapier, Integromat) to format the data structure.

Now with the REST Data Source Connector, pulling data into a data source from an external API is a whole lot simpler. Data can be pull from a Target URL, and then an array with objects can be mapped to a data source's rows/columns. 

• Adding a REST Connector
• Configuring a REST Connector
• Example JSON expression
  • JSON
  • Expressions
• Optional Settings
  • Headers
  • REST Steps

Adding a REST Connector

When logged into the web portal, navigate the side menu to Connected Data>Data Sources. 

On the Data Sources page, hover over an existing Data Source and click the Settings link.

On the Settings page, under the Connector option, click +Add Connector. 

This will bring up a list of available Connectors and click the REST option.

Configuring a REST Connector

1. Refresh Frequency

The time interval of which data is pulled and refreshed by this connector.  Options are 15 Minutes, 30 Minutes, 1 hour, 2 hours, 6 hours, 12 hours and, daily.

2. HTTP Action

Defines what kind of REST API procedure you are going to use. 

Data As - specify the format of the Rest API is.            

• JSON - JavaScript Object Notation format
• XML - eXtensible Markup Language format

3. Target URL

Specify where the request URL the data are going to be retrieved/updated.

4. Use Global Datasource REST URL

The system will use connector requests to the REST endpoint defined in Organization Setup -> Global Datasource REST URL.

5. Path Row Selector

Specify which resources are going to affect. Expressions are dependent on the value in the 'Data As' field. 

The below tables are step-by-step expression comparisons between JSON and XML syntax.

6. Response Mapping

Map the columns from the Data Source to the response values. You can define all fields or only select fields from your JSON/XML depending on the business requirement.

Path to Column Value - specify the source column you are retrieving/updating. The value of this must be the same name defined in JSON/XML.

Column Name - specify the destination column of the data.

Example JSON expression

JSON

An example of an array with objects that contain data to populate a data source.

{ "store": {    "book": [         { "category": "reference",        "author": "Nigel Rees",        "title": "Sayings of the Century",        "price": 8.95      },        { "category": "fiction",        "author": "Evelyn Waugh",        "title": "Sword of Honour",        "price": 12.99      },        { "category": "fiction",        "author": "Herman Melville",        "title": "Moby Dick",        "isbn": "0-553-21311-3",        "price": 8.99      },        { "category": "fiction",        "author": "J. R. R. Tolkien",        "title": "The Lord of the Rings",        "isbn": "0-395-19395-8",        "price": 22.99      }    ],    "bicycle": {      "color": "red",      "price": 19.95    }  }
}

Expressions

Below are the sample expressions to get a particular set of data from the JSON.

$.store.book[0].title $.store.book[*].title $..book[3] //or using brackets $['store']['book'][0].['title']
$['store']['book'][*].['title']
$..['book'][3] $.store.book[?(@.price < 10)].title

Optional Settings

Headers

Defines an option to attached custom HTTP headers in your request to the external platform. This is useful if the external system requires you to authenticate using AUTH headers containing username and password.

To add headers click the ellipsis and click Headers.

Configure the headers below

1. Key

Specify the name of the header key.

2. Value

This is the header 'key' value that will be sent to the external system as part of the header request. 

Note: You can add multiple headers in one request.

REST Steps

Allows you to have two requests in a single REST API. The first step can be from a different URL. The result of the first request can be pass to the second request.

To add REST steps click the ellipsis and click Add REST Step.

Configure the REST steps

1. HTTP Action

Defines what kind of REST API procedure you are going to use. 

Data As - specify what the format of the Rest API is.                   

• JSON - JavaScript Object Notation format
• XML - eXtensible Markup Language format

2. Target URL

Specify where the request URL the data are going to be retrieved/updated.

The added REST step is triggered first, allowing for retrieved data to be used in the request.

The result from the REST step returned as $response for use in the subsequent request below.

Access properties or lists of elements from JSON responses via the JSONVAL() and JSONLIST() formula functions.

Similarly for XML responses, use XMLVAL() and XMLLIST().

e.g. {(JSONVAL($response, 'path.to.property'))}