Set up a universal (generic) REST API connection with token authentication

You can build integrations with apps that use REST API, even if the connection is not already provided by integrator.io.

Important: A better alternative, with similar functionality and additional settings, is the universal HTTP connector. We recommend starting with that option or switching to it if you run into errors with a REST API connection.

Before creating the connection, review your app’s API guide. It will provide the information you need, such as the kind of authentication that the app requires and its URI. Every app puts its documentation – guides and reference material – in different places. You can often find it by searching for “API guide” or “API documentation” on the company’s website.

Tip: Some companies put their documentation on third-party sites. If you can’t find the guide on their website, you can also try a web search.

Contents

• A. Set up a REST connection
• B. Provide general REST connection settings
• C. Edit application details
• D. Edit token auth settings
• E. Test and save the connection

A. Set up a REST API connection

Start establishing the universal, or generic, REST API connection in either of the following ways:

• Select Connections from the Resources menu.

• • Next, click + Create connection at the top right. In the resulting Create source panel, select REST API from the Application list, under the Universal connectors group.

B. Provide general REST connection settings

Name (required): Provide a clear and distinguishable name. Throughout integrator.io imports and exports, you will have the option to choose this new connection, and a unique identifier will prove helpful later when selecting among a list of connections that you’ve created.

Application (required, non-editable): A reminder of the app you’re editing.

Note: For on-premise mode, an agent must first be installed and configured. If the system you want to connect to is behind a firewall, the agent helps connect you without having to whitelist any IPs.

Mode (required): Select one of the following options:

• Cloud to connect to a publicly accessible server application
• On-premise to connect to a server that is publicly inaccessible and has integrator.io agent installed on it

Agent (required, if On-premise selected for Mode; otherwise not displayed): Select an agent from the list. To connect to an on-premise application, integrator.io requires that an agent be installed on a networked computer. An agent is a small application that allows you to connect to data behind your firewall. When installing an agent, you will specify a unique access token, which then populates the Agent drop-down list. The installed agents connect to integrator.io and establish a reverse SSH tunnel, allowing secure communication without the need to whitelist integrator.io IP addresses in your firewall settings. A single agent can be used by multiple different connections.

C. Edit application details

Base URI (required): Enter the common part of the API’s URL to be used across all of the HTTP endpoints you invoke.

Configure HTTP headers (optional): In some rare cases, you may need to include custom HTTP headers with your API requests. integrator.io automatically adds the appropriate content-type header based on the mediaType value described in the connection associated with this request (typically application/json). Note that the request header value automatically includes the authentication method described in the associated connection if required. Use this header field in the rare case when an API requires additional headers other than application or JSON.

Media type (required): Specify the data format to use in the HTTP request body and HTTP response body.

D. Edit token auth settings

Auth type (required): Select Token if your service implements token authentication strategy. (basic, cookie-based, and custom authentication are treated separately.)

Token (required): Enter your API token. Multiple layers of protection (including AES 256 encryption) are in place to secure your API token.

Send token via (required): Select the location where your API expects to find the authentication token: 

• HTTP header: Allows you to specify the header name and authentication scheme to use when constructing the HTTP request.
• URL parameter: The authentication token is located in the URL. Specify the query string parameter name that holds the token value.

Header name (required, enabled when Send token via is set to HTTP header): Enter the header field name that contains the token, if the API expects a field other than Authorization.

Header scheme (optional): Select an HTTP authorization header scheme value. For example, Bearer would be the scheme value for Authorization: Bearer my_secret_api_token. 

Parameter name (required, enabled when Send token via is set to URL parameter): Specify the name of the URL parameter that holds the API token value. For example, if you enter myAPITokenURLParam, then all HTTP requests will be sent in the format ?myAPITokenURLParam=<token>.

Configure token refresh (optional): Check this box if your token expires after a period of time. Then, configure the additional options that appear.

HTTP method (required): If the service you’re connecting to supports token request/refresh, select the HTTP method to use in the token call. When you select POST, the setting HTTP request body is revealed, below.

Relative URI (optional): If the service you’re connecting to supports requests to obtain or refresh existing tokens, enter the URL (relative to the base URI) to use in the request token call. Click the handlebars icon to open the Advanced field editor and create or edit a template. Note that handlebars placeholders, such as {{connection.http.encrypted.password}}, may be used to reference any connection fields. Typically, a username/password or refresh token is required in the request, which you can store in the encrypted field or, if not sensitive, the unencrypted field.

Configure HTTP headers (optional): In some cases, it may be necessary to include custom HTTP headers with your token refresh requests. You can reference dynamic path field names for the connection using handlebars {{{placeholders}}}.

Override media type (optional): When the HTTP request requires a different media type than what is configured on the connection, select an alternate value.

Path to token field in HTTP response body (optional): If the service you’re connecting to supports requests to obtain or refresh tokens, enter the path contained in the HTTP response where the new token can be extracted. If no value is found at this path, then the token request is considered a failure.

E. Test and save the connection

HTTP method (optional): Select the HTTP method to use when making the ping request.

Relative URI (required): Enter the relative URI to a specific resource, as documented in your app’s API guide. (The ping URI is relative to the base URI.) This field is required for testing the connection.

Path to success field in HTTP response body (optional): Provide the location of custom error codes, as documented in the error schema in your app’s API guide.

A success path is necessary only if your app returns errors outside of the standard 4xx and 5xx status codes. For example, Slack sets a field in the response body and returns a 200 HTTP status code, whether or not the ping HTTP request failed. In such cases, for the Ping success path value, you can specify the JSON path of a field in the response body that should instead be used to determine if a ping request succeeded. For example, if you are building a connection to the Slack API, set this field to ok (see Slack API docs for more info).

Success values (optional): Enter the values to test whether a connection succeeded. This optional field is used in conjunction with the Ping success path field. The value found in the HTTP response at the path provided is compared against this list of success values. If there is an exact case-sensitive match of any of the values, then the request is considered successful.

Click Test to try connecting before you save these values. If the connection fails, double-check the provided settings, and test again.