Registering Interface and Union types on GraphQL Schema

In this post, we will explore Jaal APIs to register interface and union types. Jaal is GraphQL server library developed in Go. To learn more about GraphQL interfaces and unions, please refer to the official documentation. The basic Jaal APIs such as registering inputs, objects, queries and mutations are described in this post.

The GraphQL Schema

We will develop a GraphQL server using Jaal which will implement the following schema

The GraphQL schema defined above exposes two queries and four mutations. One query returns the MagicalCreature interface, while the other query returns MagicalObject union. The MagicalCreature interface is implemented by the Snake object and the Spider object. The MagicalObject union have the Wand and the Broomstick objects as its members.

Enough chit-chat, let’s dive into the implementation!

Step 1: Defining and registering the required types

As you can see, we have defined all the required Go types. Then we have registered them on GraphQL schema as objects and input types. We have also registered the mutations required to add data to the server. To keep this simple, we have stored the data in memory. If you want, you can use a database to store and fetch the data.

Step 2.1: Registering the GraphQL union

To register a type as a union on the GraphQL schema, we embed it with a special marker schemabuilder.Union. The union member types must be anonymous and pointers to a struct.

This marker denotes that a type should be treated as a union type by Jaal. It also denotes that the fields returning a union type should expect to return this type as a one-hot struct, i.e. only one of the type should be returned.

In our case, the type MagicalObject will be registered as a union type on GraphQL schema with Wand and Broomstick as its member. The fields returning MagicalObject should either return Wand or Broomstick but never both. That is what we have done while registering the query magicalObject.

Step 2.2: Registering the GraphQL interface

To register a type as an interface on the GraphQL schema, we embed it with a special marker schemabuilder.Interface. This marker denotes that a type should be treated as an interface type by Jaal.

The other fields of this struct are the types that implement this interface. These fields must be anonymous pointers to a struct. Jaal groups the common fields of all the types in the struct and registers the struct as an interface with these common fields.

For example, the MagicalCreature struct has two types, Spider and Snake. Both these types have fields — Id, Name, HasLegs, HasWings. Hence, Jaal registers MagicalCreature interface with these fields. We have registered query magicalCreature which returns the MagicalCreature interface.

Step 3: Running the server

Now that we have defined all the required functions, it is time to run the server and see our code in action.

Step 4: Seeing it in action

Let’s piece together our code and run it.

To run queries and mutations, we can use GraphQL Playground. To run the example, run the command go run main.go . The server will start at http://localhost:9000/graphql. The following video shows how to create and fetch a MagicalCreature and MagicalObject.

What’s next?

We explored how to register interface and union types on GraphQL schema. In the next post, we will explore how to register custom scalar types on a GraphQL server using Jaal and how to create connections (aka schema-stitching).