Connectors / Core / HTTP Client
HTTP Client
Make calls to any third-party APIOverview
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:
The endpoint you seek to use is not currently available within the service connector's operations list.
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.
USER TIP: With scenario 2 it is likely that the HTTP client connector will be used in conjunction with the Webhook Trigger. This enables users to create workflows which are also triggered by an event in the service, for which there is no official Tray.io pre-built trigger yet either.
TRAY ACADEMY: Interested in getting to grips with even more features? Why not check out our academy course: The HTTP client connector. It covers basic concepts, potential use casees, and some of the best ways to utilise specific operations.
Custom services and authentication
In order to make use of the HTTP client, you will need to build a 'Custom service' for the service you wish to make use of.
Please see our Custom services page for details on creating a service, creating authentications for it, and some advice on pitfalls and best practices.
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.
