Metadata API Reference: Actions

Introduction

actions are user defined mutations with custom business logic.

Supported from

The metadata API is supported for versions v2.0.0 and above and replaces the older schema/metadata API.

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

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/metadata 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/metadata 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/metadata 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/metadata 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