REST API datasources can be used to get data from various information systems, either from a third-party tool like a CRM or an Asset management system or from a custom software built internally in your organisation.

This page explains how to configure a REST API datasource in Elements Connect, and the different authentication modes supported.

If you want to learn how to configure a Connected item plugged to a REST API datasource you should have a look a this page.

Configure a REST API datasource

  1. From the Elements Connect global administration page, click on Datasources.

  2. Click on the Create datasource button
  3. You'll see all the different datasource types supported by Elements Connect. Click on the REST icon
  4. Enter a name for this new datasource. Click on Create.
  5. To configure the datasource, you'll be asked to set the following parameters:

Server details

ParameterDescription
API Base Url

The base URL of the REST API will be completed in each item configuration to match an endpoint of the REST API.

Example of an issue picker connected to Atlassian's Jira:

  • Datasource base url: https://jira.atlassian.com/rest/api/2 
  • Item query: /search? 
Mandatory
API DocumentationA link to the REST API documentation, will be handy when you will be configuring items connected to this datasource.
API Test URL

If provided, will be used by Elements Connect to test the connection to the REST API.
You can skip this parameter if the API Base URL is a valid URL that returns an HTTP 200 code. 

A good practice is to provide a path to a "health check" endpoint which returns a HTTP 200 code when the server is up.
For example: https://jira.atlassian.com/rest/api/2/serverInfo


Authentication

Authentication modes

Elements Connect supports 3 authentication modes:

  • No auth 
  • Basic auth
  • API Key, either set through a URL param or a HTTP header
No auth

Calls made to the REST API are not authenticated, use this mode if your REST API does not require authentication.

Basic auth

This authentication mode enables interaction with API that are protected by Basic HTTP Authentication.
When used, you'll be asked to provide a username and a password that will encoded by Elements Connect
Authorization prefixed with the chain "Basic"


Ex: With username "elements" and password "connect":

  1. Concatenated chain: elements:connect 
  2. Output of the base 64 encoding: ZWxlbWVudHM6Y29ubmVjdA== 
  3. Authorization header: Basic ZWxlbWVudHM6Y29ubmVjdA== 
API Key

An API Key is a token provided by the client to authenticate a call.
API keys can be send in a request header or a query parameter, both modes are supported by Elements Connect.
To configure an API Key authentication:

  1. Select the API Key authentication mode
  2. Select the appropriate API Key mode
  3. Provide the requested information: key and value

Elements Connect will add the key to every call made to the REST API.
Examples of REST APIs which require API key authentication:

Others

More authentication modes will be added to Elements Connect such as OAuth2 or Bearer Token.
If the authentication mode of your REST API is not supported, please contact us through our support portal.

Security

Securing sensitive data

We know that passwords and API keys are sensitive data.
For that reason and to enforce security, sensitive information:

  • are stored encrypted in our database
  • are never displayed when editing a datasource nor sent by Elements Connect REST API

Your secrets are safe with us.

HTTPS only

Elements Connect only supports the HTTPS protocol, for security reasons the HTTP protocol is not accepted.

SSL Certificates

Elements Connect always checks the validity of the SSL certificate of the domain hosting the target REST API.
You cannot provide custom SSL certificates. 

Performances

We know that performance is a key requirement for you. We don't want Elements Connect to have a negative impact on the performances of your Jira instance.
Therefore, we've designed our solution with performance in mind and have taken specific actions to make the user experience as enjoyable as possible.

Cache

AVAILABLE

To reduce the number of calls made to your REST API, results are cached by Elements Connect at datasource level. 
The cache duration is not configurable and is set to 5 minutes.

How the cache works

Let's take the example of a Connected item "Asset" connected to the REST datasource:

  • When "Asset" is edited
    • Evaluates the item query (replace dependencies by their value, if any)
    • Looks up in the cache for an entry matching the "Item" / "Evaluated Query" key
    • If there is no entry in the cache:
      • Executes the query on the REST datasource
      • If request is successful
        • Stores the raw response in the cache associated with the key "Item ID" / "Evaluated query"
      • Otherwise
        • Nothing is stored in the cache
    • If an entry is found in the cache
      • Retrieved the response from the cache

The cache is emptied periodically, all entries older than 5 minutes are removed from cache.

Timeout

AVAILABLE

Long queries can have a negative impact on the user experience, it would lead to field options taking ages to load. This is why a timeout is set on every call made to a REST API datasource.
The timeout duration is not configurable and it's set to 1 minute.

What's next