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.

Note

General information about the templating used in REST Connectors can be found in the Kriti templating section of the documentation.

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
$response.statusHTTP response staus code from the webhook

In addition to these variables, the following functions are available in addition to the standard Basic Functions:

Context variableValue
getSessionVariable(NAME)Look up a session variable by name (case-insensitive)

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.

Request URL with Query Parmeters (as key-value pairs)​

You can provide Key-Value type query params to add to the URL.

You can also 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.

Request URL with Query Parmeters (as raw string)​

You can provide string type query params to add to the URL.

You can also 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'])}}

Optional query params

Query params with key/value pairs which evaluate to null are ignored by Hasura while performing the HTTP API call. Hasura considers such query params optional.

For example, consider a query param value with template {{$session_variables?['x-hasura-user-id']}}. If the variable x-hasura-user-id is absent in the session variables, then the query param will be omitted from the HTTP API call.

Request Body​

You can generate a custom request body by configuring a template to transform the default payload to a custom payload. Request body could be provided using the body field as an object, which additionally gives the ability to disable request body, transform request body to application/json, or transform request body to x_www_form_urlencoded formats.

Disabling Request Body​

If you are using a GET request, you might want to not send any request body, and additionally not send a content-type header to the webhook. You can do that using the disable body feature.

In the Configure REST Connectors section, click on Add Request Options Transform, and convert the Request Method as GET.
Then click on Add Payload Transform, disable the payload body by using the dropdown next to the Configure Request Body section.

Disable payload body

Hit Save Action to apply your changes.

Request Body with application/json format​

You can transform Request Body to application/json format using the following steps:

In the Configure REST Connectors section, click on Add Payload Transform. By default, the Console sends the body as application/json which can be seen in the dropdown next to the Configure Request Body section.

payload body application/json

Hit Save Action to apply your changes.

Request Body with x_www_form_urlencoded format​

While doing x_www_form_urlencoded transformation, please note that as all changes to the request must be made explicit when calling the API, so you will need to remove the default application/json header and add a application/x-www-form-urlencoded header.

In the Configure REST Connectors section, click on Add Payload Transform. Change the dropdown next to Configure Request Body section to x_www_form_urlencoded. You can see the body transformed body in the Transformed Request Body section.

payload body x_www_form_urlencoded

Hit Save Action to apply your changes.

Response Body​

You can transform the default body of your HTTP API response by configuring a response transform template. This can be used to match the output types defined in your Action with your HTTP API.

Note

Response transforms are applicable only for JSON responses.

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

response transform method

Hit Create Action to apply your changes.

Note

You can also apply multiple transforms based on the following:

  1. HTTP response received from the Action webhook in the response transform template. For example:
{{ if $response.status == 200 }}
  {
    "users": {
      "name": {{$body}},
      "password": {{$body}}
    }
  }
{{ elif $response.status == 400 }}
  {
    "message": {{$body.error}}
  }
{{ else }}
  {
    "message" : "internal error"
  }
{{ end }}
  1. Session Variables. For example:
{{ if $session_variables["x-hasura-role"] == "admin" }}
  {
    "users": {
      "name": {{$body}},
      "password": {{$body}}
    }
  }
{{ elif $session_variables["x-hasura-role"] == "user" }}
  {
    "users": {
      "name": {{$body.username}},
      "password": "<redacted password>"
    }
  }
{{ else }}
  {
    "message" : "internal error"
  }
{{ end }}

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
The HasuraCon 2024 CFP is open!
Read morearrow-icon

Start with GraphQL on Hasura for Free

  • Build apps and APIs 10x faster
  • Built-in authorization and caching
  • 8x more performant than hand-rolled APIs
Try GraphQL with Hasura
Promo
Loading...