Actions transforms¶

Table of contents

Introduction
Configuring actions transforms
Types of transformations
- Request body
- Content Type
- URL
- Method
Example

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:

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:

{
  "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:

{
  "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:

{
  "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:

The transformation is given by:

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"
  }
}

« previous | next »

Want to contribute or report missing content?

edit this page on github | contributing guidelines | report an issue

Hasura GraphQL engine is open source. See license