REST API
IP allow list
If your organization has configured origin restriction, add our servers IP to the allowlist: 52.45.65.15, 3.223.15.246
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.
If you want to learn how to configure a Connected field plugged to a REST API data source you should have a look a this page.
Configure a REST API data source
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
Server details
| Parameter | Description | |
|---|---|---|
| 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:
| Mandatory |
| 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. A good practice is to provide a path to a "health check" endpoint which returns a HTTP 200 code when the server is up. |
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.
Note that these headers are not provided for authentication purposes. We recommend you do not use them to store sensitive data, such secrets or passwords.
Authentication
Authentication modes
Elements Connect supports 4 authentication modes:
- No auth
- Basic auth
- API Key, either set through a URL param or a HTTP header
- OAuth2 (client credentials grant type)
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":
- 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.
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. A the moment, the only grant type supported is client credentials.
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 this tutorial on how to connect to an Azure Active Directory using the Client Credentials grant type.
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 now 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
Check this tutorial to Connect to Salesforce
Others
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
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
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.