Schema/Metadata API Reference: Actions¶

Table of contents

Introduction
create_action
drop_action
update_action
create_action_permission
drop_action_permission

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 »