ash_graphql
ash_graphql
v0.26.0

View Source Getting Started With GraphQL

get-familiar-with-ash-resources

 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/apis.

bring-in-the-ash_graphql-dependency

 Bring in the ash_graphql dependency 

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

add-some-backwards-compatibility-configuration

 Add some backwards compatibility configuration

in config/config.exs

config :ash_graphql, :default_managed_relationship_type_name_template, :action_name

This won't be necessary after the next major release, where this new configuration will be the default.

add-the-api-extension

 Add the API Extension

Add the following to your API module. If you don't have one, be sure to start with the Ash Getting Started Guide.

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

  graphql do
    authorize? false # Defaults to `true`, use this to disable authorization for the entire API (you probably only want this while prototyping)
  end

  ... 
end

add-graphql-to-your-resources

 Add graphql to your resources

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.

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

add-ashgraphql-to-your-schema

 Add AshGraphql to your schema

If you don't have an absinthe schema, you can create one just for ash.

Define a context/1 function, and call AshGraphql.add_context/2 with the current context and your apis. Additionally, add the Absinthe.Middleware.Dataloader to your plugins, as shown below. If you're starting fresh, just copy the schema below and adjust the module name and api name.

defmodule Helpdesk.Schema do
  use Absinthe.Schema

  @apis [Helpdesk.Support]

  use AshGraphql, apis: @apis

  # The query and mutation blocks is where you can add custom absinthe code
  query do
  end

  mutation do
  end
end

connect-your-schema

 Connect your schema

using-plug

 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: Helpdesk.Schema]

forward "/playground",
  to: Absinthe.Plug.GraphiQL,
  init_opts: [
    schema: Helpdesk.Schema,
    interface: :playground
  ]

using-phoenix

 Using Phoenix

You will simply want to add some code to your router, like so.

You will also likely want to set up the "playground" for trying things out.

pipeline :graphql do
  plug AshGraphql.Plug
end

scope "/" do
  pipe_through [:graphql]

  forward "/gql", Absinthe.Plug, schema: Helpdesk.Schema

  forward "/playground",
          Absinthe.Plug.GraphiQL,
          schema: Helpdesk.Schema,
          interface: :playground
end

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.

what-s-next

 What's next?

Topics:

How Tos:

Monitoring