HTTP Client

Overview

The HTTP client connector allows you to make calls to any third-party API endpoints.

Two general scenarios which would necessitate the use of the Tray.io HTTP client connector are:

1. The endpoint you seek to use is not currently available within the service connector's operations list.

2. There is no Tray.io connector available for the service you need to reference. This means that the HTTP client connector can be used to effectively build your own connector by creating a new authentication and passing in a token as a parameter.

Custom services and authentication

To use the HTTP client, you will either need to Create a Generic Service Authentication or Create a new service for the service you wish to use

Please see our Custom services page for details on creating a service and Authenticating Connectors page for details on creating Generic Service Authentication.

Using the HTTP client

Making a GET request

Assuming you have already set up an Airtable authentication as per the Custom services page, the following example shows how you can make a basic Airtable GET request using the HTTP Client:

In this case we have had to use the Airtable API documentation to find the URL of the endpoint we wish to access.

We have also had to set an Authorization Header using the $.auth.api_key jsonpath.

This will then return the data we are looking for:

Testing your setup

The best way to check that everything is running properly is to use a manual trigger to call your API and inspect the logs to see what messages are being passed back and forth.

We also recommend using a service like Postman for exploring APIs.

HTTP client features

The HTTP client connector intelligently handles data to make things as clear, reliable and consistent as possible. Below are some of the measures we take to ensure this.

OAuth2 advanced features

There are several advanced features available within the OAuth2 Advanced properties section:

• Authorization type - Set the authorization type and HTTP headers behind the scenes. May be used in conjunction with setting up your own custom refresh logic as well.

• Follow redirect - For if you want to move a webpage to a new location (redirects are not followed by default).

• Reject unauthorised - Default is 'true', everything is HTTPS. Users are able to disable the secure functionality if need be here.

• TLS - Users can make their own HTTPS settings. By default the connector states it is coming from Tray.io but this enables users to change the security information if need be and set the TLS setting in the HTTPS request.

• Parse response - Automatically generated as a string, this can be changed to make the response JSON or XML etc.

• Force file response - Instead of returning the response as a json object, this feature returns it as a file which can be downloaded.

• Force file resonse name - The name of the file if the response is forced as a file object.

• Status codes - Depending on the version number of the workflow in question, the connector will terminate depending on the status code. This feature allows users to specify the status codes that the HTTP client should expect as per their requirements. See Dealing with statuses returned by your calls for more details below.

Dealing with statuses returned by your calls

Variables

All variables passed as query parameters are HTML-escaped automatically.

Pagination

Tray has a page limit of 1 MB. So calls to APIs may return errors if the body of the returned content is too large.

To prevent this happening, you should implement a pagination method which is appropriate to the type of API calls you are making.

Headers

Any header required by the API Service can be added, as per the 'Authorization' header in the above Making a GET request example for a token-based auth.

Content

The Content-Type header is automatically set depending on the body provided, with application/ x-www-form-urlencoded being set if none is selected.

Additionally, the Content-Type of the request can be set/ overwritten by explicitly specifying it in the header itself.

Accept

The Accept header is fixed to application/json, with a few exceptions.

If the body is set to none, or the automatically detected Content-Type (dependent on the body) is either text/ plain or application / x-www-form-urlencoded, then Accept is not set.

Additionally, the Accept value of the request can be set/ overwritten by explicitly specifying it in the header.

Binary files

It is possible to use the HTTP client connector to send files across in a binary format using the 'Body type' -> 'Binary' option.

When a user sends a file using the 'Body type': 'binary' property, Tray.io will stream the data of that object to your endpoint.

The end result will be a string output, found within your output panel under the JSON key name: "body".

For the sake of clarity, this example will use two small Tray.io workflows to show the transportation of the data more clearly.

Multipart file uploads

Note that files can also be uploaded in multiple parts when using the form-data option.

This is found within the 'Body' type field.

Import cURL

The Import cURL feature speeds up the manual process of filling in API information by auto-generating it for you.

All you need do is provide the cURL code for your chosen API call and the fields will populate.

Example use case

Say there is an API call that retrieves candidates from a recruitment platform 'Acme'.

curl -X GET https://api.acme.com/v1/candidates -H "Authorization: Bearer YOUR_API_KEY"

Below is an example of how we would use the cURL feature to auto-populate all the required fields.