Schema/Metadata API Reference: Actions

Introduction

actions are user defined mutations with custom business logic.

create_action

create_action is used to define an action. There shouldn’t be an existing action with the same name.

Create a synchronous action with name create_user:

POST /v1/query 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
      },
      "comment": "Custom action to create user"
   }
}

Args syntax

Key Required Schema Description
name true ActionName Name of the action
definition true ActionDefinition Definition of the action
comment false text comment

ActionDefinition

Key Required Schema Description
arguments false Array of InputArgument Input arguments
output_type true GraphQLType The output type of the action. Only object and list of objects are allowed.
kind false [ synchronous | asynchronous ] The kind of the mutation action (default: synchronous). If the type of the action is query then the kind field should be omitted.
headers false [ HeaderFromValue | HeaderFromEnv ] List of defined headers to be sent to the handler
forward_client_headers false boolean If set to true the client headers are forwarded to the webhook handler (default: false)
handler true WebhookURL The action’s webhook URL
type false [ mutation | query ] The type of the action (default: mutation)
timeout false Integer Number of seconds to wait for response before timing out. Default: 30

InputArgument

Key Required Schema Description
name true text Name of the argument
type true GraphQLType Type of the argument

Note

The GraphQL Types used in creating an action must be defined before via Custom Types

drop_action

drop_action is used to remove an action. Permissions defined on the actions are also dropped automatically.

Drop an action create_user:

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

{
   "type":"drop_action",
   "args":{
      "name":"create_user",
      "clear_data": true
   }
}

Args syntax

Key Required Schema Description
name true ActionName Name of the action
clear_data false boolean If set to true and action kind is asynchronous, related data is deleted from catalog. (default: true)

update_action

update_action is used to update the definition of the action. Definition thus provided is replaced with existing one.

Update an action create_user by making it’s kind to asynchronous:

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

{
   "type":"update_action",
   "args":{
      "name":"create_user",
      "definition":{
         "kind":"asynchronous",
         "arguments":[
            {
               "name":"username",
               "type":"String!"
            },
            {
               "name":"email",
               "type":"String!"
            }
         ],
         "output_type":"User",
         "handler":"https://action.my_app.com/create-user"
      }
   }
}

Args syntax

Key Required Schema Description
name true ActionName Name of the action
definition true ActionDefinition Definition of the action to be replaced

create_action_permission

create_action_permission is used to define a permission to make action visible for a role.

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

{
  "type": "create_action_permission",
  "args": {
    "action": "create_user",
    "role": "user"
  }
}

Args syntax

Key Required Schema Description
action true ActionName Name of the action
role true RoleName Name of the role
comment false text comment

drop_action_permission

drop_action_permission is used to drop a permission defined on an action.

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

{
  "type": "drop_action_permission",
  "args": {
    "action": "create_user",
    "role": "user"
  }
}

Args syntax

Key Required Schema Description
name true ActionName Name of the action
role true RoleName Name of the role
« previous | next »
Want to contribute or report missing content?

Powered by Sphinx. | Copyright © 2021 Hasura.