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

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

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.

1. Create the REST API connection

1. Sign in to integrator.io.
2. From the Resources menu, select Connections. The resulting page displays a list of all of the connections in your account.
3. Click + Create connection at the top right. The Create connection pane opens.
4. Select REST API from the list of connection types. (It is usually quickest to enter a few characters to start searching.)

5. Give your connection a name that is meaningful to your integration and that can help you identify it later in a list of connections, and click Next.

2. Identify the location where the REST API is running

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): Choose either... 

• Cloud – Connect to an app on the cloud.
• On-premise – An on-premise app runs locally on the company’s servers. This mode requires an integrator.io agent:
  
  • From the Agent dropdown, select an installed agent.

3. Authorize the connection

Continuing in the Create connection pane, at a minimum you must provide your username and password to establish a connection with basic authentication.

Authentication type (required): Select Basic if your service implements the HTTP basic authentication strategy. (Cookie-based, custom, and token authentication are treated separately.) This authentication method adds Base64-encoded username and password values in the Authentication HTTP request header.

Configure HTTP headers (optional): Specify additional parameters as name-value pairs to pass in the header, as needed for your integration.

Username (required): Enter the basic authentication username for the server.

Password (required): Enter the password. Multiple layers of protection are in place, including AES 256 encryption, to keep your password safe.  

Base URI (required): Enter the base URI, which is the path to the app’s API, as documented in the API guide. 

Media type (required): Choose the format for your records.

4. Test and save the connection

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

Ping 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.

Ping success path (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).

Ping 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 connection to try connecting before you save these values. If the connection fails, double-check the provided settings, and test again.