Set up a universal (generic) REST API connection with cookie-based authentication

You can build integrations with apps that use REST API, even if the connection is not already provided by Celigo 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 Tools menu, select Flow Builder.
3. When exporting data from this app, click into the Source application search bar. 
      – or –
   When importing data into this app, click into the Destination application search bar.
4. Select REST API from the list of connection types. (It is usually quickest to enter a few characters to start searching.)

5. At the top right, click the Save and continue button.

2. Name the connection and choose its mode

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.

Name (required): Give your connection a name that is meaningful to your integration and that can help you identify it later in a list of connections.

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. Describe the connection

Continuing in the Establish your REST API connection dialog, describe the server you’re connecting to. To authenticate with a cookie, a session will be created and stored after your credentials are verified. That session is then given an ID.

Authentication type (required): Select Cookie in this context. (Basic, custom, and token authentication are treated separately.)

Configure HTTP headers (optional): Click this button to pass additional parameters in the header. Configure any headers as needed for your integration, providing the names and values in the resulting editor.

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.

Cookie method (required): Select the HTTP method, GET or POST, to use when querying the cookie.

Cookie URI (required): Enter the relative URI to the cookie. (The cookie URI is relative to the base URI.)

Cookie success status code (optional): Specify the expected status code for success.

4. Test and save the connection

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

Ping URI (optional): 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.)

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 this case, in Ping success path 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 for Slack’s 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 to try connecting before you save these values. If the connection fails, double-check the provided settings, and test again.