Getting Started With GraphQL

View Source

Get familiar with Ash resources

If you haven't already, read the Ash Getting Started Guide. This assumes that you already have resources set up, and only gives you the steps to add AshGraphql to your resources/domains.

Installation 

mix igniter.install ash_graphql

Manual

Bring in the ash_graphql dependency

def deps()
  [
    ...
    {:ash_graphql, "~> 1.7.8"}
  ]
end

Setting up your schema

If you don't have an absinthe schema, you can create one just for ash. Replace helpdesk in the examples with your own application name.

See the SDL file guide for more information on using the SDL file, or remove the generate_sdl_file option to skip generating it on calls to mix ash.codegen.

in lib/helpdesk/schema.ex

defmodule Helpdesk.GraphqlSchema do
  use Absinthe.Schema

  # Add your domains here
  use AshGraphql,
    domains: [Your.Domains]

  query do
    # Custom absinthe queries can be placed here
    @desc "Remove me once you have a query of your own!"
    field :remove_me, :string do
      resolve fn _, _, _ ->
        {:ok, "Remove me!"}
      end
    end
  end

  mutation do
    # Custom absinthe mutations can be placed here
  end
end

Connect your schema

Using Phoenix

Add the following code to your Phoenix router. It's useful to set up the Absinthe playground for trying things out, but it's optional.

pipeline :graphql do
  plug AshGraphql.Plug
end

scope "/gql" do
  pipe_through [:graphql]

  forward "/playground",
          Absinthe.Plug.GraphiQL,
          schema: Module.concat(["Helpdesk.GraphqlSchema"]),
          interface: :playground

  forward "/",
    Absinthe.Plug,
    schema: Module.concat(["Helpdesk.GraphqlSchema"])
end

Whats up with Module.concat/1?

This Module.concat/1 prevents a compile-time dependency from this router module to the schema module. It is an implementation detail of how forward/2 works that you end up with a compile-time dependency on the schema, but there is no need for this dependency, and that dependency can have drastic impacts on your compile times in certain scenarios.

If you started with mix new ... instead of mix phx.new ... and you want to still use Phoenix, the fastest path that way is typically to just create a new Phoenix application and copy your resources/config over.

Using Plug

If you are unfamiliar with how plug works, this guide will be helpful for understanding it. It also guides you through adding plug to your application.

Then you can use a Plug.Router and forward to your plugs similar to how it is done for phoenix:

plug AshGraphql.Plug

forward "/gql",
  to: Absinthe.Plug,
  init_opts: [schema: Module.concat(["Helpdesk.GraphqlSchema"])]

forward "/playground",
  to: Absinthe.Plug.GraphiQL,
  init_opts: [
    schema: Module.concat(["Helpdesk.GraphqlSchema"]),
    interface: :playground
  ]

For information on why we are using Module.concat/1, see the note above in the Phoenix section.

Select domains to show in your GraphQL

In the use AshGraphql call in your schema, you specify which domains you want to expose in your GraphQL API. Add any domains that will have AshGraphql queries/mutations to the domains list. For example:

use AshGraphql, domains: [Your.Domain1, Your.Domain2]

Adding Queries and Mutations

Some example queries/mutations are shown below. If no queries/mutations are added, nothing will show up in the GraphQL API, so be sure to set one up if you want to try it out.

Queries & Mutations on the Resource

Here we show queries and mutations being added to the resource, but you can also define them on the domain. See below for an equivalent definition

defmodule Helpdesk.Support.Ticket do
  use Ash.Resource,
    ...,
    extensions: [
      AshGraphql.Resource
    ]

  graphql do
    type :ticket

    queries do
      # Examples

      # create a field called `get_ticket` that uses the `read` read action to fetch a single ticke
      get :get_ticket, :read
      # create a field called `most_important_ticket` that uses the `most_important` read action to fetch a single record
      read_one :most_important_ticket, :most_important

      # create a field called `list_tickets` that uses the `read` read action to fetch a list of tickets
      list :list_tickets, :read
    end

    mutations do
      # Examples

      create :create_ticket, :create
      update :update_ticket, :update
      destroy :destroy_ticket, :destroy
    end
  end

  ...
end

Queries & Mutations on the Domain 

defmodule Helpdesk.Support.Ticket do
  use Ash.Resource,
    ...,
    extensions: [
      AshGraphql.Resource
    ]

  # The resource still determines its type, and any other resource/type-based
  # configuration
  graphql do
    type :ticket
  end

  ...
end

defmodule Helpdesk.Support do
  use Ash.Domain,
    extensions: [
      AshGraphql.Domain
    ]

  ...
  graphql do
    # equivalent queries and mutations, but the first argument
    # is the resource because the domain can define queries for
    # any of its resources
    queries do
      get Helpdesk.Support.Ticket, :get_ticket, :read
      read_one Helpdesk.Support.Ticket, :most_important_ticket, :most_important
      list Helpdesk.Support.Ticket, :list_tickets, :read
    end

    mutations do
      create Helpdesk.Support.Ticket, :create_ticket, :create
      update Helpdesk.Support.Ticket, :update_ticket, :update
      destroy Helpdesk.Support.Ticket, :destroy_ticket, :destroy
    end
end

What's next?

Topics:

How Tos: