Running Our Query with GraphiQL

GraphiQL is “an in-browser IDE for exploring GraphQL,” and to make things easy for the user, Absinthe integrates with three versions of GraphiQL: the official interface,^[10] an advanced version,^[11] and GraphQL Playground.^[12] All three are built in to the absinthe_plug^[13] package and ready to go with just a little configuration.

The absinthe_plug dependency is already in our mix.exs file from the initial setup, but we need to now configure the Phoenix router to use it. Replace the existing "/" scope with the following block:

Really, we’re setting up two routes: "/api" with the regular Absinthe.Plug, and "/graphiql" with the GraphiQL plug. The former is what API clients would use and what we’ll use in our tests, and then the latter provides the “in-browser” IDE we’ll use now. Specifically, we’re going to use the simplified, official GraphiQL interface, set with the interface: :simple option.

Let’s start our application by running the following:

Since the server will start on port 4000, visit http://localhost:4000/graphiql (adding the path where you have mounted GraphiQL) and see the GraphiQL user interface.

There’s a lot to see here, but let’s give our query a shot before we dig into it much further. Start by typing your query into the text area to the top left.

Did you notice that while you were typing, GraphiQL helpfully suggested some autocompletions? That’s because when you loaded the page, it automatically sent an introspection query to your GraphQL API, retrieving the metadata it needs about PlateSlateWeb.Schema to support autocompletion and display documentation.

When you press the play button above the query, you can see the JSON result in the right-hand text area as shown in the top figure.

Success! Now, let’s try this one, adding the :id field:

Here’s the result:

It’s handy being able to specify additional fields in our query without having to modify the schema any further! We already defined the :id field on our :menu_item type, so it works out of the box. We just weren’t asking for it before.

What else can we query? Let’s look at the API documentation that GraphiQL has collected for us. To the right of the GraphiQL interface, there’s a “Docs” link that, when clicked, will open up a new sidebar full of API documentation:

If you click on RootQueryType, you can see the menuItems field with its type, [MenuItem], displayed, but it’s missing a more detailed description. You can add one by editing your schema.

Let’s do that now. Back in web/schema.ex, you can add a :description value as part of the third argument to the field macro:

If you look back at GraphiQL (refresh the page), your description will now be displayed.

There’s another technique you can use to add descriptions, using a module attribute, @desc, just as you would with Elixir’s @doc:

Because the latter approach supports multiline documentation more cleanly and sets itself off from the working details of our field definitions, it’s the approach we’ll use in our application.