Http Client Connectormake calls to any REST API
The Tray HTTP Client provides a way to manually make REST-based requests to a specified URL. You can use the HTTP client to make calls to any REST API.
There are two main uses for this connector:
To make a call to an endpoint which is not yet used by any of the operations available in the Tray connector for e.g. Salesforce, Hubspot, Trello, Airtable, etc.
If no Tray connector actually exists for a service, it can also be used to effectively build your own connector by creating a new authentication and passing a token as a parameter. Note, however, that this can currently only be done for token-based services. If the service in question is OAuth-based it is only possible to extend the functionality of a pre-existing Tray connector (as explained below) - because you currently cannot use the HTTP Client to create an OAuth-based authentication from scratch.
In this case it is likely that you will wish to use the HTTP Client in conjunction with the Webhook Trigger. This will enable you to create workflows which are also triggered by an event in the service for which there is as yet no Tray pre-built trigger or connector.
The HTTP Client intelligently handles data to make things as simple, reliable and consistent as possible. Here's some of the measures we take:
- All variables passed as query parameters are HTML-escaped automatically
- 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.
- 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.
The available operations are GET, POST, PUT, PATCH, DELETE and HEAD
The HTTP Client connector allows basic authentication.
It does not yet support OAuth. However if you have an OAuth-based service connector that has already been authenticated, you can re-use this to build some extra custom functionality for the service. Please see the section on this below.
Creating a non-OAuth Authentication
Note: The exact requirements for authenticating API calls will vary from service to service. Via the service API documentation, you will need to research exactly what format is expected, as well as how individual endpoints are used and what query parameters are expected.
You can create and use an authentication in 2 steps:
Add a new authentication (for example a token) by clicking Add Authentication and choosing a name for your auth token. Then enter the actual token (note that when you create a token as in the below gif, you can call it anything you want - token, access_token, api_token etc.):
The created authentication can then be used in your API call by including the path "$.auth.token_name" (token_name will change depending on how you named it in step 1). Depending on the exact requirements of the service you are connecting to, this could be as a token in the query parameters:
Or it could be that it needs to be passed as a Bearer in the header:
Note: different APIs need to be authenticated in different ways, for example via:
Query parameters (as in the first example above)
Headers (as in the second example above)
Basic authentication (username & password)
Access tokens (OAuth refresh)
To view settings related to the last two, click on "Show advanced settings" for the properties and you'll see the following:
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.
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.
Dealing with Statuses returned by your calls
Each time an operation makes a call, as long as a connection is made and a status is returned Tray will not consider that an error has occurred - i.e. a status of '403 - Forbidden' or '504 - Gateway Timeout' will not result in a Tray error which would be managed using our Error Handling methods.
If 4xx and 5xx statuses are likely to be encountered, the Tray boolean and branch connectors can be used to set up a path for dealing with these cases.
Note on Using OAuth
If you have a service which uses OAuth that you have already authenticated to using its pre-built connector, you can re-use this OAuth in an http-client.
For example, if you have already used and authenticated with the pre-built Slack connector in a workflow, you can click 'Show Advanced Settings' and see what the config json path is for the OAuth token - i.e.
Having noted this config path, you can now create an http client connector for adding custom Slack API operations.
To test this out, you can try a quick setup which will post a message to a particular Slack channel:
Create a new Workflow with a Manual Trigger
Add an Http Client as the next step
Choose your previously configured Slack Auth as the Authentication, set the API Operation to POST and enter
https://slack.com/api/chat.postMessageas the endpoint URL:
Now you need to specify some query parameters:
As you can see you need to enter the Slack Channel ID (found in the url when you have selected a particular channel e.g.
https://acme.slack.com/messages/CE2DU9XSL/), the text for your message and the OAuth token config path.
Details on the accepted format of parameters for this Slack API are at https://api.slack.com/methods/chat.postMessage
Once you have finished, you can click 'Run Workflow Now' and the test message should be sent and you can check the debug info: