REST API

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

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

IP allow list

If your organization has configured some origin restriction on your database, make sure to add our servers IP addresses to your IP allow list:

52.45.65.15
3.223.15.246

Create the REST API connection

From the Elements Connect global administration page, click on Data sources.
Click on the Create data source button
Select REST API option and click on next
Enter a name for this new data source. Click on Create.

Configure the REST API connection

Once the connection has been created, you need to configure it.

Server details

Parameter

Description

API Base Url

MANDATORY

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?

API Documentation

A 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

Custom headers

Some services require clients to pass custom headers during connection process.
Configure up to 20 HTTP headers to be sent when querying a REST API data source.
Simply provide a name and a value for the header.

Some header names are forbidden, i.e. those that cannot be modified programmatically. You can find a non-exhaustive list of forbidden header names here.

Please note that these headers are not provided for authentication purposes. We strongly advise that you do not use them to store sensitive data, such as secrets or passwords.

Authentication

Elements Connect supports the following authentication modes:

No auth
Basic auth
API Key
OAuth 2 - Client credentials
OAuth 2 - Authorization Code

If the authentication mode of your REST API is not supported, please contact us through our support portal.

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 credentials (a username and a password) that will encoded by Elements Connect.

Credentials encoding example
For a username "elements" and password "connect".

Concatenated chain: elements:connect
Output of the base 64 encoding: ZWxlbWVudHM6Y29ubmVjdA==
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:

Select the API Key authentication mode
Select the appropriate API Key mode
Provide the requested information: key and value

Elements Connect will add the key to every call made to the REST API.

Here are some examples of REST APIs which require API key authentication:

OAuth 2 - Client credentials

The OAuth 2.0 Authorization Framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner (usually an end user) and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

Elements Connect REST API datasource supports OAuth 2.0, which is also supported by many Cloud services such as those provided by Google, Salesforce, Facebook and Microsoft.

The Client Credentials flow doesn't support refresh tokens. The client is already trusted by the authorization server, requesting a valid access token when the previous one expires is enough.

We provide the following tutorial on how to connect to an Azure Active Directory using the Client Credentials grant type: Configure an Azure Active Directory as a datasource.

OAuth 2 - Authorization Code

The OAuth 2.0 Authorization Code Flow is a secure protocol for user authentication and authorization in applications. It allows users to grant permissions to third-party apps without sharing their login credentials.

Here's a simplified overview:

Authorization Request: The app redirects the user to the authorization server's endpoint, including the app's details and requested permissions.
User Authentication: The user logs in and verifies their identity with the authorization server.
User Consent: The authorization server asks the user to approve the app's request for access to their resources.
Authorization Code: If consent is given, the authorization server provides the app with an authorization code.
Token Request: The app sends the authorization code to the authorization server and requests an access token.
Token Response: The authorization server validates the code and issues an access token, allowing the app to access protected resources on behalf of the user.
Access Protected Resources: The app includes the access token in its requests to the resource server to retrieve the user's protected resources.
Token Refresh: If the access token expires, the app can use a refresh token to obtain a new access token without involving the user.

With Elements Connect, you can use the OAuth 2.0 Authorization Code Flow to fetch values from the following services:

Salesforce
Google APIs (such as Google Drive, Gmail, and Google Calendar)
Microsoft Graph API (for accessing Microsoft services like Office 365 and Outlook)
GitHub API
Dropbox API

We provide the following tutorial on how to connect to Salesforce through the Auythorization Code grant type: Get client data from Salesforce CRM into JSM requests.

Security

Securing sensitive data

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

sensitive data are stored encrypted in our database
sensitive data are never displayed when editing a data source nor sent by Elements Connect REST API

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

How does cache / caching data works in Elements Connect?

Timeout

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.

Known limitation

Please note that for the moment, our platform supports REST API data sources that return responses in JSON format only. We are aware of the demand for XML response compatibility and are considering this feature for future updates.