Packages
ash_graphql
1.0.0-rc.4
1.10.0
1.9.4
1.9.3
1.9.2
1.9.1
1.9.0
1.8.5
1.8.4
1.8.3
1.8.2
1.8.1
1.8.0
1.7.17
1.7.16
1.7.15
1.7.14
1.7.13
1.7.12
1.7.11
1.7.10
1.7.9
1.7.8
1.7.7
1.7.6
1.7.5
1.7.4
1.7.3
1.7.2
1.7.1
1.7.0
1.6.0
1.5.1
1.5.0
1.4.7
1.4.6
1.4.5
1.4.4
1.4.3
1.4.2
1.4.1
1.4.0
1.3.4
1.3.3
1.3.2
1.3.1
1.3.0
1.2.1
1.2.0
1.1.1
1.1.0
1.0.1
1.0.0
1.0.0-rc.5
1.0.0-rc.4
retired
1.0.0-rc.3
1.0.0-rc.2
1.0.0-rc.1
1.0.0-rc.0
0.28.1
0.28.0
0.27.1
0.27.0
0.26.9
0.26.8
0.26.7
0.26.6
0.26.5
0.26.4
0.26.3
0.26.2
0.26.0
0.25.13
0.25.12
0.25.10
0.25.9
0.25.8
0.25.7
0.25.6
0.25.5
0.25.4
0.25.3
0.25.2
0.25.1
0.25.0
0.24.1
0.24.0
0.23.3
0.23.2
0.23.1
0.23.0
0.22.13
0.22.12
0.22.11
0.22.10
0.22.9
0.22.8
0.22.7
0.22.6
0.22.4
0.22.3
0.22.2
0.22.1
0.22.0
0.21.0
retired
0.20.5
0.20.4
0.20.3
0.20.2
0.20.1
0.20.0-rc.3
0.20.0-rc.2
0.20.0-rc.1
0.20.0-rc.0
0.19.0
0.18.0-rc0
0.17.5
0.17.5-rc0
0.17.4
0.17.2
0.17.1
0.17.0
0.16.28
0.16.27
0.16.26
0.16.25
0.16.24
0.16.23
0.16.22
0.16.21
0.16.20
0.16.18-rc5
0.16.18-rc4
0.16.18-rc3
0.16.18-rc2
0.16.18-rc1
0.16.18-rc0
0.16.17
0.16.16
0.16.15
0.16.14
0.16.13
0.16.12
0.16.11
0.16.10
0.16.9
0.16.8
0.16.7
0.16.6
0.16.5
0.16.4
0.16.3
0.16.2
0.16.1
0.16.0
0.15.10
0.15.9
0.15.8
0.15.7
0.15.6
0.15.5
0.15.4
0.15.3
0.15.2
0.15.1
0.15.0
0.14.1
0.14.0
0.13.1
0.13.0
0.12.5
0.12.4
0.12.3
0.12.1
0.12.0
0.10.0
0.9.5
0.9.4
0.9.3
0.9.2
0.9.1
0.9.0
0.8.0
0.7.5
0.7.4
0.7.3
0.7.2
0.7.1
0.7.0
0.6.3
0.6.2
0.6.1
0.6.0
0.5.0
0.4.0
0.3.2
0.3.1
0.3.0
0.2.1
0.2.0
0.1.3
0.1.2
The extension for building GraphQL APIs with Ash
Retired package: Release invalid - Actor is not properly set when calling bulk actions
Current section
Files
Jump to
Current section
Files
documentation/tutorials/getting-started-with-graphql.md
# Getting Started With GraphQL
## Get familiar with Ash resources
If you haven't already, read the [Ash Getting Started Guide](https://hexdocs.pm/ash/get-started.html). This assumes that you already have resources set up, and only gives you the steps to _add_ AshGraphql to your resources/domains.
## Bring in the ash_graphql dependency
```elixir
def deps()
[
...
{:ash_graphql, "~> 1.0.0-rc.4"}
]
end
```
## Add the domain Extension
Add the following to your domain module. If you don't have one, be sure to start with the [Ash Getting Started Guide](https://hexdocs.pm/ash/get-started.html).
```elixir
defmodule Helpdesk.Support do
use Ash.Domain, extensions: [
AshGraphql.Domain
]
graphql do
authorize? false # Defaults to `true`, use this to disable authorization for the entire domain (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.
```elixir
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.
in `lib/helpdesk/schema.ex`
```elixir
defmodule Helpdesk.GraphqlSchema do
use Absinthe.Schema
use AshGraphql, domains: [Helpdesk.Support]
# The query and mutation blocks is where you can add custom absinthe code
query do
end
mutation do
end
end
```
## Connect your schema
### 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.
```elixir
pipeline :graphql do
plug AshGraphql.Plug
end
scope "/" do
pipe_through [:graphql]
forward "/gql",
Absinthe.Plug,
schema: Module.concat(["Helpdesk.GraphqlSchema"])
forward "/playground",
Absinthe.Plug.GraphiQL,
schema: Module.concat(["Helpdesk.GraphqlSchema"]),
interface: :playground
end
```
> ### Whats up with `Module.concat/1`? {: .info}
>
> This `Module.concat/1` prevents a [compile-time dependency](https://dashbit.co/blog/speeding-up-re-compilation-of-elixir-projects) 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](https://elixirschool.com/en/lessons/specifics/plug/#dependencies) 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](https://hexdocs.pm/plug/Plug.Router.html#forward/2) to your plugs similar to how it is done for phoenix:
```elixir
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.
## What's next?
Topics:
- [GraphQL Generation](/documentation/topics/graphql-generation.md)
How Tos:
- [Authorize With GraphQL](/documentation/how_to/authorize-with-graphql.md)
- [Handle Errors](/documentation/how_to/handle-errors.md)
- [Use Enums with GraphQL](/documentation/how_to/use-enums-with-graphql.md)
- [Use JSON with GraphQL](/documentation/how_to/use-json-with-graphql.md)
[Monitoring](/documentation/monitoring.md)