Open Navigation

Http Client Connector

make calls to any REST, SOAP or GraphQL API

Overview

The Tray HTTP Client provides a way to manually make API requests to a specified URL. You can use the HTTP client to make calls to any REST-based, SOAP-based or GraphQL-based API.

There are two main uses for this connector:

  1. 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.

  2. 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.

    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

Basic (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:

  1. 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.):


  2. 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:

    token-as-query-parameter

    Or it could be that it needs to be passed as a Bearer in the header:

    token-as-bearer

    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:

    http-basic-auth

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.

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.

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.


OAuth Authentications


Using existing OAuth authentications

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.

To test this out, you can try a quick setup which will post a message to a particular Slack channel:

  1. Create a new Workflow with a Manual Trigger

  2. Add an Http Client as the next step

  3. Choose your previously configured Slack Auth as the Authentication, set the API Operation to POST and enter https://slack.com/api/chat.postMessage as the endpoint URL:

    http-client-slack-1

  4. Now you need to specify some query parameters:

    slack-http-params-1

    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/) and the text for your message.

    As another parameter, you have to add the token which can use an auto-completed jsonpath to pull the access token from the auth details:


    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:

    slack-http-debug

Adding a new OAuth service

It is also possible to build an OAuth2 authentication 'from scratch' by clicking on the Add a new service link in the HTTP Client's new auth dialog:

oauth-add-new-service

When creating a new service you are presented with the following screen which asks you to enter several details, including the following OAuth2 settings:

oauth2-settings

For each service you wish to configure you will have to:

  • create a custom app in the service UI so as to generate a Client ID and Client Secret.
  • obtain the generic endpoints the service makes available for Authentication URL and Access Token URL (these invariably end in /authorization and /token)
  • add the Tray.io redirect url https://auth.tray.io/oauth2/token to the custom app settings in the service UI
  • investigate the required access 'scopes' (i.e. permissions) and endpoint involved in making the desired call to the service API so you can build your individual operations

Example service - Spotify

To give you an example of how this is done, we will take you through investigating and setting up a simple call using the Spotify API.

The ultimate aim here will be to produce an API call which carries out the simple task of listing a Spotify User's saved albums.

1 - Create a custom app in your Service

The first stage of the process is to create a new Spotify app:

spotify-dboard-create-app

2 - Get Client ID and Client Secret

You are then presented with your Client ID and Client Secret:

spotify-client-id-secret

These can then be added to the service fields above.

3 - Get Authentication URL and AccessToken URL

All services have specific OAuth endpoints for authentication and access tokens. These endpoints invariably end in /authorization and /token

To get these exact fields for a particular service, you can google for e.g. 'spotify authorization oauth' or 'hubspot authorization oauth'.

With Spotify this leads us to a page https://developer.spotify.com/documentation/general/guides/authorization-guide/ (if you were using a different service such as Hubspot, you would come to a similar page such as https://developers.hubspot.com/docs/methods/oauth2/oauth2-quickstart

In the spotify authorization page you will find the following example authorization call:

spotify-auth-call

This gives us the https://accounts.spotify.com/authorize url which can be used to populate the Authentication URL.

On the same Spotify page we can search for '/token' and find the token url:

spotify-token-url

This gives us the https://accounts.spotify.com/api/token url which can be use to populate the Access Token URL.

4 - Set the Tray.io Redirect URL (done in the service dashboard)

Each service will need to be told what is the Redirect URL made available by the Tray platform.

This is https://auth.tray.io/oauth2/token and is found in the Tray.io new service page:

tray-redirect-url

This will need to be entered in the settings of your custom app:

enter-redirect-url

Note: If possible, as above it is recommended that you add two redirect urls - one with a / and one without, to account for the fact that some services only work with a / and some won't.

5 - Set Scopes

To control the level of access you want your Tray authentication to have you can set the 'scopes'.

You will need to find a page which lists the OAuth scopes for your service, such as https://developer.spotify.com/documentation/general/guides/scopes/:

spotify-list-scopes

In this example we are just wanting to list albums a user has saved, so we can use the user-library-read scope:

set-scope

6 - Completing and using the service setup

We now have all the detals we need filled in for the service:

complete-service

Once the service is added you can return to your workflow and select it from the dropdown list:

select-service-dd

And you can confirm the scopes being requested:

confrim-scopes

7 - Constructing an API call

Finding the exact call you want to make will require some investigation of the API for the service. In this case we have found the following page which gives us the API to list a user's saved albums:

spotify-api-get-user-alnums

So we can now construct the GET request in the Tray.io builder as such:

tray-spotify-get-request

Note that we have used interpolated mode to add Bearer {$.auth.access_token} as an Authorization key in the 'Headers' section.

This is because, back on https://developer.spotify.com/documentation/general/guides/authorization-guide/, we find an example call to the spotify API which uses an OAuth token:

spotify-example-token-call

Testing the call

If we run the workflow we can then check the debug output to make sure it has been successful.

Adding extra parameters

Note that when setting up your service it is possible to add extra parameters, to allow for certain services that expect particular parameters present in a particular way in the Query or Headers section of the call:

extra-params

Was this article helpful?
Yes
No