Skip to main content
Version: v2.x

Create Actions

Introduction​

An action is a GraphQL query or mutation. You have to define the GraphQL type of the arguments that the query or mutation accepts and the GraphQL type of its response.

To create an action, you have to:

  1. Define the query or mutation
  2. Define the required types
  3. Create a handler

Let's look at examples for mutation and query type Actions.

Setup​

There is no setup required for defining Actions via the Console.

Mutation type action​

Let's start with a mutation that accepts a username and password, and returns an access token. We'll call this mutation login.

Step 1: Define your mutation and associated types​

Start with defining the mutation and the required types. These types will reflect in the GraphQL schema.

Go to the Actions tab on the Console and click on Create. This will take you to a page like this:

Console Action create

Define the Action as follows in the Action Definition editor.

type Mutation {
  login(username: String!, password: String!): LoginResponse
}

In the above action, we called the returning object type to be LoginResponse. Define it in the New types definition as:

type LoginResponse {
  accessToken: String!
}

The above definition means:

  • This action will be available in your GraphQL schema as a mutation called login.
  • It accepts two arguments called username and password of type String!.
  • It returns an output type called LoginResponse.
  • LoginResponse is a simple object type with a field called accessToken of type String!.
Note

When using a numeric value in an Action, the value is coerced to its expected scalar type based on type of the input value supplied (from the Action payload). As stated in the spec, a GraphQL service (such as Hasura) will attempt to coerce numeric values to Int, Float, or String types, so long as its reasonable and doesn't result in the loss of data. Otherwise, the service will throw an error.

Step 2: Create the action handler​

A handler is an HTTP webhook where you can perform the custom logic for the action.

In this case, we will just return an access token, but typically you would want to run all the business logic that the action demands. NodeJS/Express code for this handler would look something like:

const handler = (req, resp) => {
  // You can access their arguments input at req.body.input
  const { username, password } = req.body.input;

  // perform your custom business logic
  // check if the username and password are valid and login the user

  // return the response
  return resp.json({
    accessToken: 'Ew8jkGCNDGAo7p35RV72e0Lk3RGJoJKB',
  });
};

You can deploy this code somewhere and get the URI. For getting started quickly, we also have this handler ready at https://hasura-actions-demo.glitch.me/login.

Set the handler

Now, set the handler for the action:

Set the value of the handler field to the above endpoint.


URL templating

To manage handler endpoints across environments it is possible to template the endpoints using ENV variables.

e.g. https://my-handler-endpoint/addNumbers can be templated to {{ACTION_BASE_ENDPOINT}}/addNumbers where ACTION_BASE_ENDPOINT is an ENV variable whose value is set to https://my-handler-endpoint

Note

If you are running Hasura using Docker, ensure that the Hasura Docker container can reach the handler endpoint. See this page for Docker networking.

Step 3: Finish action creation​

Finally, to save the action:

Hit Create.

Step 4: Try it out​

In the Hasura Console, head to the API tab and try out the new action.

GraphiQL
Query Variables
Request Headers
Documentation Explorer
No Schema Available

And that's it. You have extended your Hasura schema with a new mutation.

Query type action​

Let's start with a basic query that accepts a list of numbers and returns their sum. We'll call this query addNumbers.

Step 1: Define your query and associated types​

Start with defining the query and the required types. These types will reflect in the GraphQL schema.

Go to the Actions tab on the Console and click on Create. This will take you to a page like this:

Console action create

Define the Action as follows in the Action Definition editor.

type Query {
  addNumbers(numbers: [Int]): AddResult
}

In the above action, we called the returning object type to be AddResult. Define it in the New types definition as:

type AddResult {
  sum: Int
}

The above definition means:

  • This action will be available in your GraphQL schema as a query called addNumbers
  • It accepts an argument called numbers which is a list of integers.
  • It returns an output type called AddResult.
  • AddResult is a simple object type with a field called sum of type integer.
Note

When using a numeric value in an Action, the value is coerced to its expected scalar type based on type of the input value supplied (from the Action payload). As stated in the spec, a GraphQL service (such as Hasura) will attempt to coerce numeric values to Int, Float, or String types, so long as its reasonable and doesn't result in the loss of data. Otherwise, the service will throw an error.

You can also use Type Generator feature to generate the types for your Action:

Console Action create

Insert JSON samples for the request and the response, click "Insert Types" and Hasura generates the GraphQL types for you.

Step 2: Create the action handler​

A handler is an HTTP webhook where you can perform the custom logic for the action.

In this case, it is the addition of the numbers. NodeJS/Express code for this handler would look something like:

const handler = (req, resp) => {
  // You can access their arguments input at req.body.input
  const { numbers } = req.body.input;

  // perform your custom business logic
  // return an error or response
  try {
    return resp.json({
      sum: numbers.reduce((s, n) => s + n, 0),
    });
  } catch (e) {
    console.error(e);
    return resp.status(500).json({
      message: 'unexpected',
    });
  }
};

You can deploy this code somewhere and get the URI. For getting started quickly, we also have this handler ready at https://hasura-actions-demo.glitch.me/addNumbers.

Set the handler

Now, set the handler for the action:

Set the value of the handler field to the above endpoint.

URL templating

To manage handler endpoints across environments it is possible to template the endpoints using ENV variables.

e.g. https://my-handler-endpoint/addNumbers can be templated to {{ACTION_BASE_ENDPOINT}}/addNumbers where ACTION_BASE_ENDPOINT is an ENV variable whose value is set to https://my-handler-endpoint

Step 3: Finish action creation​

Finally, to save the action:

Hit Create.

Step 4: Try it out​

In the Hasura Console, head to the API tab and try out the new action.

GraphiQL
Query Variables
Request Headers
Documentation Explorer
No Schema Available

And that's it. You have extended your Hasura schema with a new query.

Additional Resources

Introduction to Hasura Actions - View Recording.

Start with GraphQL on Hasura for Free

  • Build apps and APIs 10x faster
  • Built-in authorization and caching
  • 8x more performant than hand-rolled APIs
Try GraphQL with Hasura
Promo
Loading...
Loading...