2020-03-11 13:09:25 +03:00
|
|
|
.. meta::
|
|
|
|
:description: Action handlers for Hasura actions
|
|
|
|
:keywords: hasura, docs, actions, handlers
|
|
|
|
|
2020-03-11 22:42:36 +03:00
|
|
|
.. _action_handlers:
|
|
|
|
|
2020-02-24 19:19:14 +03:00
|
|
|
Action handlers
|
|
|
|
===============
|
|
|
|
|
|
|
|
|
|
|
|
.. contents:: Table of contents
|
|
|
|
:backlinks: none
|
|
|
|
:depth: 1
|
|
|
|
:local:
|
|
|
|
|
|
|
|
Introduction
|
|
|
|
------------
|
|
|
|
|
|
|
|
Actions need to be backed by custom business logic. This business logic can be
|
|
|
|
defined in a handler which is an HTTP webhook.
|
|
|
|
|
|
|
|
|
|
|
|
HTTP handler
|
|
|
|
------------
|
|
|
|
|
2020-04-16 10:25:19 +03:00
|
|
|
When the action is executed i.e. when the query or the mutation is called, Hasura makes a ``POST`` request to the
|
|
|
|
handler with the action arguments and the session variables.
|
2020-02-24 19:19:14 +03:00
|
|
|
|
|
|
|
The request payload is of the format:
|
|
|
|
|
|
|
|
.. code-block:: json
|
|
|
|
|
|
|
|
{
|
2020-04-24 10:55:51 +03:00
|
|
|
"action": {
|
|
|
|
"name": "<action-name>"
|
|
|
|
},
|
2020-02-24 19:19:14 +03:00
|
|
|
"input": {
|
|
|
|
"arg1": "<value>",
|
|
|
|
"arg2": "<value>"
|
|
|
|
},
|
|
|
|
"session_variables": {
|
|
|
|
"x-hasura-user-id": "<session user id>",
|
|
|
|
"x-hasura-role": "<session user role>"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
Returning a success response
|
|
|
|
----------------------------
|
|
|
|
|
|
|
|
To return a success response, you must send back a response payload of action's
|
|
|
|
response type. The HTTP status code must be ``2xx`` for a successful response.
|
|
|
|
|
|
|
|
Returning an error response
|
|
|
|
---------------------------
|
|
|
|
|
2020-03-03 15:02:40 +03:00
|
|
|
To return an error response, you must send back an error object.
|
|
|
|
An error object looks like:
|
2020-02-24 19:19:14 +03:00
|
|
|
|
|
|
|
.. code-block:: json
|
|
|
|
|
|
|
|
{
|
2020-03-03 15:02:40 +03:00
|
|
|
"message": "<mandatory error message>",
|
|
|
|
"code": "<optional error code>"
|
2020-02-24 19:19:14 +03:00
|
|
|
}
|
|
|
|
|
|
|
|
The HTTP status code must be ``4xx`` for an error response.
|
|
|
|
|
|
|
|
|
|
|
|
Example
|
|
|
|
-------
|
|
|
|
|
|
|
|
For example, consider the following mutation.
|
|
|
|
|
|
|
|
.. code-block:: graphql
|
|
|
|
|
|
|
|
extend type Mutation {
|
|
|
|
UserLogin (username: String!, email: String!): UserInfo
|
|
|
|
}
|
|
|
|
|
|
|
|
type UserInfo {
|
|
|
|
accessToken: String!
|
|
|
|
userId: Int!
|
|
|
|
}
|
|
|
|
|
|
|
|
Let's say, the following mutation is executed:
|
|
|
|
|
2020-04-24 10:55:51 +03:00
|
|
|
.. code-block:: graphql
|
2020-02-24 19:19:14 +03:00
|
|
|
|
|
|
|
mutation {
|
|
|
|
UserLogin (username: "jake", password: "secretpassword") {
|
|
|
|
accessToken
|
|
|
|
userId
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
Hasura will call the handler with the following payload:
|
|
|
|
|
|
|
|
.. code-block:: json
|
|
|
|
|
|
|
|
{
|
2020-05-05 06:46:39 +03:00
|
|
|
"action": {
|
|
|
|
"name": "UserLogin"
|
|
|
|
},
|
2020-02-24 19:19:14 +03:00
|
|
|
"input": {
|
|
|
|
"username": "jake",
|
|
|
|
"password": "secretpassword"
|
|
|
|
},
|
|
|
|
"session_variables": {
|
|
|
|
"x-hasura-user-id": "423",
|
|
|
|
"x-hasura-role": "user"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
To return a success response, you must send the response of the action's output
|
|
|
|
type (in this case, ``UserInfo``) with a status code ``2xx``. So a sample
|
|
|
|
response would be:
|
|
|
|
|
|
|
|
.. code-block:: json
|
|
|
|
|
|
|
|
{
|
|
|
|
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC",
|
|
|
|
"userId": 4829
|
|
|
|
}
|
|
|
|
|
2020-02-25 18:30:00 +03:00
|
|
|
To throw an error, you must a response payload of the following type while
|
2020-02-24 19:19:14 +03:00
|
|
|
setting the status code as ``4xx``.
|
|
|
|
|
|
|
|
.. code-block:: json
|
|
|
|
|
|
|
|
{
|
|
|
|
"message": "invalid credentials"
|
|
|
|
}
|