Fundamentals of HTTP connections

Several settings are available for configuring an integrator.io HTTP connection.

Name (required): Enter a unique name for your connection so that you can easily reference it from other parts of the application.

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

Mode (required): Two options are available for this field:

This section is expanded by default, since it contains required settings.

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

Tip

If a prebuilt connector exists for the application you are connecting to, after entering the base URI, you can optionally select a prebuilt application connector with a simple form view. A prebuilt connector has a simple form view that hides or disables all unneccesary fields (including Base URI) and displays only the fields necessary to establish a connection with the branded application. A prebuilt connector has a simple form view that hides or disables all unneccesary fields (including Base URI) and displays only the fields necessary to establish a connection with the branded application. To review documentation for a prebuilt application connector, search the knowledge base for your connector. For example, if you want to switch to the simple view for the Stripe connector, you can search for "Stripe" or "Set up a connection to Stripe" to find the application-specific documents. To remove the simple form view, click Clear selection. You can also ignore the simple form view and continue using the HTTP form view.

Configure HTTP headers (optional): In some cases, it may be necessary to include custom HTTP headers with your token refresh requests. integrator.io automatically adds the appropriate content-type header based on the Media type of the connection (typically, and by default application/json). Note that this request header value automatically includes the Auth type of this connection. You can reference dynamic path field names for the connection using handlebars {{{placeholders}}}.

Media type (required): This setting specifies the data format to use in the HTTP request body and response body. For example, if your API uses the JSON media type to send HTTP responses, select JSON. Options include:

Override media type for success responses (optional): Select an alternate format if successful HTTP responses return a different media type than the original HTTP request body.

Override media type for error responses (optional): Select an alternate format if unsuccessful HTTP responses return a different media type than the original HTTP request body.

Each Auth type (documented independently) requires unique settings for account authorization, depending on your selection:

Most APIs limit the number of requests that can be sent for a given time period. The following settings in this section of the connection help you to define the custom rate-limit settings for connecting to your API.

Wait time between HTTP requests (optional): This field lets you set the speed at which integrator.io makes requests. In other words, how long should the platform wait before making subsequent HTTP requests calls to the API? Wait time between HTTP requests should be set if the API does not implement rate-limiting and integrator.io should manually regulate call frequency. Enter the value for this field setting in milliseconds (integers, without the unit). Note that this field can be used only when the Concurrency level is set to 1.

Override HTTP status code for rate-limit errors (optional): The HTTP specification states that rate-limit response errors should return a 429 status code. Some APIs have custom rate-limit implementations that rely on other status codes or even throttle errors within the HTTP body. Enter a value if the service you are connecting to uses a status code other than 429.

Path to rate-limit error field in HTTP response body (optional): If the service you are connecting to embeds rate limit errors within the HTTP body, provide the path (JSON path or XPATH) within the response body where integrator.io should look to identify a throttled response. If there is a specific value (or set of values) that indicates rate-limit response at this path, use the Rate-limit error values setting for further instructions on how to identify this type of error.

Rate-limit error values (optional): If you provided a path in the HTTP response body field (above), then enter the exact values that the API will return to indicate rate-limit errors. Separate multiple values with a comma.

Override retry-after HTTP response header name (optional): HTTP services commonly return status code 429 when too many requests are made in a short period of time. This code typically accompanies a retry-after HTTP header response that specifies the time to wait until a successful request can be made. If the API returns this response header with a different name, specify the custom name in this setting.

HTTP Response Code: 500
HTTP Response Body: 
  {
    status: "Internal Server Error"
  }

HTTP Response Code: 400
HTTP Response Body: 
  {
    status: "Throttled"
  }
HTTP Response Headers: 
  {
    try-after: "1000"
  }

If you describe the connection’s test, or ping, values, then integrator.io will show you the connection’s status based on the test location’s response.

Some non-REST–based APIs return a successful HTTP status code even though the HTTP request has failed. These HTTP connect settings allow you to handle status codes that do not follow the REST standard completely (2xx status codes for successful requests and 4xx status codes for failed requests).

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

Relative URI (optional): Enter a URI to an authenticated endpoint – relative to your Base URI, above – that integrator.io will use in an HTTP request to verify that a connection is working properly (for example: /me, /tokenInfo, or /currentTime. Whenever a connection is saved, integrator.io will send a ping request to this URI and then save this connection if the request succeeds. Click the handlebars button () to open the Advanced field editor and create or edit a template. Note that handlebars {{placeholders}} may be used to reference any connection fields.

An automated batch process runs several times per hour to ping all offline connections to try to bring them back online (and to resume any data flows that were paused as a result). When you set the Relative URI for all your custom connections, then integrator.io can do more to identify offline connections and automatically restore them.

If your API has the endpoint https://abc123.com/v1/order, enter the following values for each setting:

HTTP request body (optional, enabled when HTTP method is POST or PUT): Enter an HTTP request body if the API does not accept the GET method for ping requests. integrator.io will send this value to the endpoint in the HTTP request body.

The format depends on the API being used: url-encoded, JSON, or XML. Click the handlebars button () to open the Advanced field editor and create or edit a template. Note that this field can contain handlebars {{{placeholders}}} that will be resolved according to your connection and export data. For example, if the export request body requires an authentication token to be embedded, you could enter {{connection.http.auth.token.token}}.

Path to error field in HTTP response body (optional): Enter a value if the API always returns a successful HTTP status code, but then passes an error response within a field in the HTTP response body. For example, if the API always returns a 200 (success) HTTP status code and indicates failure via an error.message field in the HTTP response body, then enter error.message.

Error values (optional): If you provided a path in the HTTP response body field (above), then enter the exact values that the API will return to indicate a failed ping response. Separate multiple values with a comma.

Path to success field in HTTP response body (optional): Enter a value if the API always returns a successful HTTP status code, but then passes a successful response within a field in the HTTP response body.

Success values (optional): If you provided a path in the HTTP response body field (above), then enter the exact values that the API will return to indicate a successful ping response. Separate multiple values with a comma.

Path to detailed error message field in HTTP response body (optional): Provide a field only if the API returns a field in the HTTP response body to indicate ping response errors.

Any detailed error message will be displayed on the error management dashboard. If this field is not set, then the full HTTP response body will be used as the error message on the dashboard.

HTTP Response Code: 200
HTTP Response Body:
  {
    status: "success"
  }

HTTP Response Code: 200
HTTP Response Body:
  {
    status: "failed"
  }

HTTP Response Code: 200
HTTP Response Body:
  {}

HTTP Response Code: 200
HTTP Response Body:
  {
    Error: "Request_Failed",
    "Error_Description": "Service is unavailable. Please try after some time."
  }

PFX and PEM certificate formats

Disable strict SSL (optional): An optional flag to skip verifying the SSL certificate, allowing self-signed or expired certificates. It is highly recommended that you never set this flag to override encryption for any production data connections. Disable at your own risk.

Borrow concurrency from (optional): If you have multiple connections to the same API, you can set the related connections to have a shared concurrency level using this field. This field is applicable only when you have the field Concurrency level set for one connection.

Auto-recover rate limit errors : This setting is enabled by default with a pre-defined value for Target concurrency level . You can disable the setting if required. To set or make changes in any of these settings, you must have administer or manage permissions .

Target concurrency level: This field is shown only if Auto-recover rate limit errors is enabled. Change the predefined value as required to limit the number of concurrent API requests allowed by the connection resource. See also, Setting currency level on a connection.

Concurrency level: When Auto-recover rate limit errors is enabled, the Concurrency level cannot be edited and shows the concurrency that the platform is currently using (runtime). When Auto-recover rate limit errors is not enabled, set this field to limit the number of concurrent HTTP requests allowed by the connection resource at any one time.

If you leave this field blank, burst mode is used. With burst mode, integrator.io will make HTTP requests as fast as possible, with very high levels of concurrency.

Some APIs respond well with burst mode and can typically handle high volumes. Conversely, other APIs are much stricter when it comes to the number of API requests being sent to their servers, and burst mode may not be recommended.

Also, every connection in integrator.io is mapped to a first-in/first-out (FIFO) queue, from which messages are processed to complete the flow execution. If you set Concurrency level to 5, at most 5 simultaneous messages are processed from the queue. See Example B below for practical guidance.

SSL certificate type (optional): Some APIs use “certificate-based authentication,” in which a digital certificate is used to identify a user, machine, or device before granting access to a resource, network, or application. If your API requires that a certificate be sent while making a HTTP request, choose to enter the certificate in either PEM or PFX format.

SSL client key (optional): Enter the private key associated with the certificate provided for the SSL client certificate. Typically, any SSL certificate is associated with a private key, which is used for encrypting/decrypting the data in SSL communication. This value is expected to be in .KEY format.

SSL certificate (optional): Some APIs use “certificate-based authentication,” in which a digital certificate is used to identify a user, machine, or device before granting access to a resource, network, or application. If your API requires that a certificate be sent while making a HTTP request, enter the certificate in PFX or PEM format.

SSL passphrase (optional): In cases where the private key is encrypted, enter the passphrase, which is used to decrypt the private key. The key can be entered in plain text.

Encrypted (optional): Use this encrypted JSON setting to store all the security-sensitive fields needed by your imports and exports (to access the application being integrated). For example, {'password': 'ayTb53Img!do'} or {'token': 'x7ygd4njlwerf63nhg'}.

Unencrypted (optional): Use this JSON field to store all the non-security–sensitive fields needed by your imports and exports (to access the application being integrated). For example: {'email':'my_email@company.com', 'accountId': '5765432', 'role': 'admin'}.

Follow the steps below to create an HTTP connection, to the Zendesk API in this example.