Schema/Metadata API Reference: Actions¶
Table of contents
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"
},
"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) |
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 |
