REST Connectors for actions

Introduction

REST Connectors for actions are used to integrate existing REST APIs as GraphQL APIs without changing any upstream code.

REST Connectors work by changing the default HTTP request made by an action to a different HTTP request by adding suitable transforms.

Supported from

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

Configuring REST Connectors

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
Will be added soon

REST Connectors 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 transforms

REST Connectors allows you to add different types of “transforms” to the default HTTP request. You can also use “context variables” in the transforms to achieve dynamic behaviour for each request.

Context Variables

The context variables available in transforms are:

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

Sample Context

The console allows you to provide mock session variables and env variables to test your transforms.

Configure an env var in the action webhook handler.

Console action webhook handler

Add the env var value to the Sample Context under Sample Env Variables.

Console action context env

The value should be reflected in the {{$base_url}} in Change Request Options section:

Console action req options transformation

Session vars can also be added to the Sample context as shown above, and used like so: {{$session_variables['x-hasura-user-id']}}. The above screen also shows an example of using the session vars from context.

Context variables validation error

Actual environment variables are not resolved during testing transforms as it could expose sensitive information to the UI.

Note that if you don’t provide mock env/session variables and test your transform, you would get a UI validation error. Considering this section is only used for testing, Create Action button will still be usable. When you click on Create Action, any referenced envs are validated at the server without leaking any sensitive information to the UI.

Request body

Generate a 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:

Add payload transformation
Will be added soon
{
  "request_transform": {
     "body": "{\n  \"users\": {\n    \"name\": {{$body.input.arg1.username}},\n    \"password\": {{$body.input.arg1.password}}\n  }\n}",
  }
}

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.
Will be added 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 REST Connectors section, click on Add Request Options Transform:

Change request URL
Will be added soon
{
  "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 REST Connectors section, click on Add Request Options Transform:

Change request method
Will be added soon
{
  "request_transform": {
     "method": "GET"
  }
}

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
Will be added soon

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