The REST Data Source Connector allows you to pull data from an external API into a data source and populate 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, a custom API, or Appenate’s API.

However, getting the data into the correct format generally requires a few changes to its structure before it can be used in the app or our web portal. You can code this yourself or utilize a third-party service (e.g., Zapier, Integromat) to format the data structure.

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

Adding a REST Data Source Connector

Data Source Settings

Navigate the side menu to Data Hub > Data Sources
Hover over a data source and click the “Settings” icon link ()
In Settings, hit the “Add Connector” button
Select the relevant option to add the connector

This will refresh the page with the newly added connector ready for configuration.

Nothing has been saved at this stage, so save your connector after making any changes to enable or update it.

Alternatively, if you’re viewing the rows of a data source, you can navigate to the Settings page using the option under the page’s title.

Configuring a REST Data Source Connector

Refresh Frequency

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

Using Connection

Allows you to select a REST connection. If the 3rd party endpoints are using oAuth 2.0, this is required as the Authentication and Access Token are retrieved in the REST Connections.

HTTP Action

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

Method	Description
GET	Use GET requests to retrieve resource representation and not modify it in any way.
POST	Use POST to create a new row in the source database table.
PUT	Use PUT primarily to update an existing resource.
DELETE	As the name applies, DELETE is used to delete resources.
PATCH	PATCH requests are to make a partial update on a resource.

Data As – specify the format of the Rest API.

JSON – JavaScript Object Notation format
XML – eXtensible Markup Language format

Target URL

Specify where the request URL and the data will 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 is 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’))}

Whitelisting Platform IP Address

If you’re having difficulty connecting to an API endpoint and your communication with the endpoint appears to be blocked and not going through, it may be necessary to whitelist our platform’s IP address with the REST API endpoint you are trying to communicate with.

Use Global Datasource REST URL

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

Path Row Selector

Specify which resources to affect. Expressions depend on the value in the ‘Data As’ field.

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

JSON	Wildcard. All objects/elements, regardless of their names.	Description
$	/	the root object/element
@	.	the current object/element
. or []	/	child operator
n/a	..	parent operator
..	//	recursive descent
*	*	Wildcard. All objects/elements regardless of their names.
n/a	@	Attribute access. JSON structures don’t have attributes.
[]	[]	Subscript operator. XPath uses it to iterate over element collections and for predicates.
[,]	\|	Union operator in XPath results in a combination of node sets. JSONPath allows alternate names or array indices as a set.
[start:end:step]	n/a	array slice operator
?()	[]	Applies a filter (script) expression.
()	n/a	script expression, using the underlying script engine.
n/a	()	groupings

Response Mapping

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

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

Column Name – specify the data’s destination column.

JSON

Example JSON expression

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 data set 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

This defines an option to attach 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 your username and password.

Click the Headers option on the connector to display Key and Value properties.

Key

Specify the name of the header key.

Value

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

Multiple Headers

You can add multiple headers in one request.

Body

Customize the Body on a single or a second-step request.

Add REST Step

This allows you to have two requests in a single REST API. The first step can be from a different URL, and the result of the first request can be passed to the second request.

Click the Add REST Step option to create Step 1 and Step 2 to be configured.

Data Source Connector – REST