View Source Getting Started With GraphQL
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
def deps()
[
...
{:ash_graphql, "~> 0.26.2"}
]
end
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 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
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
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
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
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?
Topics:
How Tos: