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
- Sign in to integrato.io.
- From the Resources menu, select Connections. The resulting page displays a list of all of the connections in your account.
- Click + Create connection at the top right. The Create connection pane opens.
- Select REST API from the list of connection types. (It is usually quickest to enter a few characters to start searching.)
-
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. Describe the connection
Continuing in the Create connection pane, provide information about the token.
Authentication type (required): Select Token in this context. (Basic, cookie-based, and custom authentication are treated separately.)
Configure HTTP headers (optional): Specify additional parameters as name-value pairs to pass in the header, as needed for your integration.
Token (required): Enter your API token. Multiple layers of protection (including AES 256 encryption) are in place to secure your API token.
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. Specify how to send the token
Next, the Create connection pane asks how to send the token. Again refer to the API guide for the service you want to connect to, in order to specify where the token should go.
The How to send token? options differ, depending on whether you select HTTP Header or URL parameter for the Location field.
Header name (optional): By default, integrator.io will send all authentication info in the Authorization: HTTP header field. If the REST API you are connecting to requires a different HTTP header, enter just the name here, without the colon (:).
Scheme (optional): Select an authentication scheme, per the API documentation. By default, integrator.io will follow the HTTP specification with regard to authentication scheme names (such as Bearer, OAuth 2.0, and MAC). If the REST API you are connecting to does not follow the specs exactly, you can provide an override by selecting None for the scheme.
Configure token refresh (optional): Check this box if your token expires after a period of time. A series of new fields will appear in the form:
Refresh token URI (optional): Enter the relative URI for refreshing the token.
Refresh token media type (optional): Select a data format.
Refresh token method (optional): Select the HTTP method to use.
Refresh token path (optional): Specify the path to the token, if the refresh token will be in the body of the response.
Refresh token headers (optional): Click to set custom headers for refreshing your token. The editor works like Configure HTTP headers, above.
Rest token parameter (optional): Specify the name of the URL parameter that will hold the API token value. For example, if you specify myAPITokenURLParam, then all HTTP requests will include
?myAPITokenURLParam=bearerToken in the URL.
The token entered in the API token field above is passed in the URL. Be assured that integrator.io has multiple layers of protection (including AES 256 encryption) in place to secure your API token.
Configure token refresh (optional): Check this box if your token expires after a period of time. A series of new fields will appear in the form:
Refresh token URI (optional): Enter the relative URI for refreshing the token.
Refresh token media type (optional): Select a data format.
Refresh token method (optional): Select the HTTP method to use.
Refresh token path (optional): Specify the path to the token, if the refresh token will be in the body of the response.
Refresh token headers (optional): Click to set custom headers for refreshing your token. The editor works like Configure HTTP headers, above.
5. 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.
Comments
0 comments
Please sign in to leave a comment.