Skip to main content
Version: v2.x

REST Connectors for actions

Introduction

REST Connectors for actions are used to integrate existing REST APIs to the GraphQL API without needing any middleware or modifications to the upstream code.

REST Connectors modify the default HTTP request made by an action to adapt to your webhook's expected format by adding suitable transforms.

Supported from

REST Connectors are supported in Hasura GraphQL Engine versions v2.1.0 and above

Configuring REST Connectors

REST Connectors can be configured either when creating a new action or editing an existing one. See the transform options here:

Go to the Actions tab on the console and create or modify an action. Scroll down to Configure REST Connectors section:

Configure REST connectors for actions

Context Variables

You can use context variables in the transforms to achieve dynamic behavior for each request.

The context variables available in transforms are:

Context variableValue
$bodyOriginal body of action request
$base_urlOriginal configured webhook handler URL
$session_variablesSession variables

Console sample context

The console allows you to preview your transforms while configuring them. To avoid exposing sensitive information on the console UI the actual environment variables configured on the server are not resolved while displaying the previews. Also any session variables used in the transform will not be available at the time of configuration.

Hence, the console allows you to provide mock env variables and session variables to verify your transforms. If you configure your transforms without providing the mock env/session variables you might see a UI validation error in the preview sections.

For example: If your webhook handler is set as an env var as shown below then pass a mock value for that env var in the sample context:

Console action webhook handler

You can enter the mock env/session variables under Configure REST Connectors > Sample Context:

Add generic sample context
Note

As the sample context is only used for previews, you can still configure the transforms on the console without setting any sample context.

Types of transforms

REST Connectors allow you to add different transforms to the default HTTP request. You can also use context variables in the transforms to achieve dynamic behavior for each request.

You can transform your:

Request Method

You can change the request method to adapt to your API's expected format.

In the Configure REST Connectors section, click on Add Request Options Transform:

Change request method

Request URL

The Request URL template allows you to configure the exact API endpoint to call.

You can use the context variables to construct the final URL.

You can also provide query params to add to the URL.

You can use the Kriti templating language to construct any string values here.

In the Configure REST Connectors section, click on Add Request Options Transform:

Change request URL

The value of the final url should be reflected in the Preview section given all required sample context is set.

Hit Save Action to apply your changes.

escapeUri

Note that you must use the escapeUri function to urlencode templated values. For example, if you have to use session variables in the URL and those may contain non-ASCII values, then you should provide the template URL as {{$base_url}}/{{escapeUri $session_variables['x-hasura-user-id']}}

Request Content-Type

You can change the Content-Type of the request to either application/json or x-www-form-urlencoded. The default is application/json.

Console support coming soon.

With x-www-form-urlencoded, the key-value pairs in body are transformed to name={{$body.input.name}}&key2={{$body.input.email}}.

Request Body

You can generate a custom request body by configuring a template to transform the default payload to a custom payload. The body field takes a template in the Kriti templating language to evaluate the transform.

In the Configure REST Connectors section, click on Add Payload Transform:

A sample payload input auto-generated based on your schema is shown.

Add payload transformation

The transformed sample payload should be shown as the Transformed Request Body given all required sample context is set.

Hit Save Action to apply your changes.

Example

Let's integrate Auth0's management API to update the profile of a user:

Go to the Actions tab on the console and create or modify an action. Scroll down to Configure REST Connectors section:

Action definition:

Example rest connector for actions

The transformation is given by:

Example rest connector for actions
Example rest connector for actions