REST API
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
From the Elements Connect global administration page, click on Datasources.
- Click on the Create datasource button
- You'll see all the different datasource types supported by Elements Connect. Click on the REST icon
- Enter a name for this new datasource. Click on Create.
- To configure the datasource, you'll be asked to set the following parameters:
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. |
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":
- 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:
- Airtable
- Google APIs
- Github
- Hubspot
- Stripe
- Twilio
- Insightly
- ServiceNow
- Zabbix
- Datadog
- Monday
- BambooHR
- OpenWeatherMap
- Amazon API Gateway
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.