REST Connectors for actions¶
Table of contents
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:
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.
Add the env var value to the Sample Context under Sample Env Variables.
The value should be reflected in the {{$base_url}} in Change Request Options section:
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:
{
"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.
{
"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:
{
"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:
{
"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:
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"
}
}
Thank you for subscribing to our newsletter!
