Actions transforms

Introduction

Transforms are used to perform custom transformations on the HTTP request generated by an action. This can be used to integrate any existing API without needing to write or deploy any middleware code. Action transforms can be seen as “REST connectors” as you can integrate any REST endpoint as a GraphQL API with a suitable transformation.

Supported from

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

Configuring actions transforms

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

Configure action transformation

Action transforms can be added to actions using the create_action metadata API or update_action metadata API by adding a request_transform field to the args:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type":"create_action",
   "args":{
      "name":"create_user",
      "definition":{
         "kind":"synchronous",
         "arguments":[
            {
               "name":"username",
               "type":"String!"
            },
            {
               "name":"email",
               "type":"String!"
            }
         ],
         "output_type":"User",
         "handler":"https://action.my_app.com/create-user",
         "timeout":60,
         "request_transform": {
            "body": "{{$body.input.name}}"
         },
      },
     "comment": "Custom action to create user"
   }
}

Types of transformations

You can practically create an arbitrary request using the context available in the Action execution. The context variables available during transformation are:

Context variable Value
$body Original body of action request
$base_url Original configured URL
$session_variables Session variables

Request body

Generate a custom body by giving a body key to the request_transform. You can use the Kriti templating language to construct the body.

In the Configure Transformations section, click on Add Payload Transformation:

Add payload transformation
{
  "request_transform": {
     "body": {
         "name": "{{$body.input.name}}",
         "email": "{{$body.input.email}}"
     }
  }
}

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.
{
  "request_transform": {
     "body": {
         "name": "{{$body.input.name}}",
         "email": "{{$body.input.email}}",
     },
     "content_type": "x-www-form-urlencoded"
  }
}

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

URL

Transform the request URL. This can be used to embed, say user-id, in the url path. You can also provide query_params to add to the URL. You can use the Kriti templating language to construct any string value here.

In the Configure Transformations section, click on Add Request Options Transformation:

Console action create
{
  "request_transform": {
    "url": "{{$base_url}}/{{$session_variables['x-hasura-user-id']}}",
    "query_params": {
       "param1": "{{$body.input.value1}}",
       "param2": "{{$body.input.value2}}"
    }
  }
}

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']}}

Method

Transform the method. This can be used to change the request method, say from POST to GET, as shown below.

In the Configure Transformations section, click on Add Request Options Transformation:

Console action create
{
  "request_transform": {
     "method": "GET",
     "url": "$base_url/{{$session_variables['x-hasura-user-id']}}"
  }
}

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 Transformations section:

Action definition:

Console action create

The transformation is given by:

Console action create Console action create

Action definition:

type Mutation {
  updateProfile(picture_url : String!) : ProfileOutput
}

type ProfileOutput {
  id: String!
  user_metadata: String!
}

The transform is given by:

{
  "request_transform": {
    "body": "{\"user_metadata\": {\"picture\": {{$body.input.picture_url}} } }",
    "url": "{{$base_url}}/{{$session_variables['x-hasura-user-id']}}",
    "method": "PATCH"
  }
}