2023-01-24 16:42:11 +13:00
# Getting Started With GraphQL
2020-08-14 10:55:34 +12:00
## Get familiar with Ash resources
2024-04-02 07:03:06 +13:00
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.
2020-08-14 10:55:34 +12:00
2023-08-01 07:17:10 +12:00
## Bring in the ash_graphql dependency
2020-11-06 14:59:06 +13:00
```elixir
def deps()
[
...
2024-03-31 10:38:35 +13:00
{:ash_graphql, "~> 0.28.0"}
2020-11-06 14:59:06 +13:00
]
end
```
2023-03-22 16:06:58 +13:00
## Add some backwards compatibility configuration
in `config/config.exs`
```elixir
config :ash_graphql, :default_managed_relationship_type_name_template, :action_name
2024-02-01 11:52:01 +13:00
config :ash_graphql, :allow_non_null_mutation_arguments?, true
2023-03-22 16:06:58 +13:00
```
This won't be necessary after the next major release, where this new configuration will be the default.
2024-04-02 07:03:06 +13:00
## Add the domain Extension
2020-08-14 10:55:34 +12:00
2024-04-02 07:03:06 +13:00
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 ).
2023-01-30 13:03:59 +13:00
2020-08-14 10:55:34 +12:00
```elixir
2023-01-30 13:03:59 +13:00
defmodule Helpdesk.Support do
2024-04-02 07:03:06 +13:00
use Ash.Domain, extensions: [
AshGraphql.Domain
2020-08-14 10:55:34 +12:00
]
2020-09-24 12:54:57 +12:00
2020-08-14 10:55:34 +12:00
graphql do
2024-04-02 07:03:06 +13:00
authorize? false # Defaults to `true` , use this to disable authorization for the entire domain (you probably only want this while prototyping)
2020-08-14 10:55:34 +12:00
end
2023-01-30 13:03:59 +13:00
2023-10-13 04:24:47 +13:00
...
2020-08-14 10:55:34 +12:00
end
```
## Add graphql to your resources
2023-01-30 13:03:59 +13:00
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.
2020-08-14 10:55:34 +12:00
```elixir
2023-01-30 13:03:59 +13:00
defmodule Helpdesk.Support.Ticket. do
2020-08-14 10:55:34 +12:00
use Ash.Resource,
2023-01-30 13:03:59 +13:00
...,
2020-08-14 10:55:34 +12:00
extensions: [
AshGraphql.Resource
]
2020-09-24 12:54:57 +12:00
2020-08-14 10:55:34 +12:00
graphql do
2023-01-30 13:03:59 +13:00
type :ticket
2020-09-24 12:54:57 +12:00
2020-08-14 10:55:34 +12:00
queries do
2023-01-30 13:03:59 +13:00
# Examples
# create a field called `get_ticket` that uses the `read` read action to fetch a single ticke
2023-10-13 04:24:47 +13:00
get :get_ticket, :read
2023-01-30 13:03:59 +13:00
# create a field called `most_important_ticket` that uses the `most_important` read action to fetch a single record
2023-10-13 04:24:47 +13:00
read_one :most_important_ticket, :most_important
2023-01-30 13:03:59 +13:00
# create a field called `list_tickets` that uses the `read` read action to fetch a list of tickets
2023-10-13 04:24:47 +13:00
list :list_tickets, :read
2020-08-14 10:55:34 +12:00
end
2020-09-24 12:54:57 +12:00
2020-08-14 10:55:34 +12:00
mutations do
2023-01-30 13:03:59 +13:00
# Examples
create :create_ticket, :create
update :update_ticket, :update
destroy :destroy_ticket, :destroy
2020-08-14 10:55:34 +12:00
end
end
2023-01-30 13:03:59 +13:00
...
2020-08-14 10:55:34 +12:00
end
```
## Add AshGraphql to your schema
2022-09-07 10:24:02 +12:00
If you don't have an absinthe schema, you can create one just for ash.
2021-03-13 03:19:19 +13:00
2023-10-13 04:24:47 +13:00
in `lib/helpdesk/schema.ex`
2021-03-13 03:19:19 +13:00
2020-08-14 10:55:34 +12:00
```elixir
2023-01-30 13:03:59 +13:00
defmodule Helpdesk.Schema do
2020-08-14 10:55:34 +12:00
use Absinthe.Schema
2024-04-02 07:03:06 +13:00
@domains [Helpdesk.Support]
2020-09-24 12:54:57 +12:00
2024-04-02 07:03:06 +13:00
use AshGraphql, domains: @domains
2020-08-14 10:55:34 +12:00
2022-11-02 14:58:41 +13:00
# The query and mutation blocks is where you can add custom absinthe code
2022-11-01 06:07:15 +13:00
query do
end
2022-11-02 14:58:41 +13:00
mutation do
end
2020-08-14 10:55:34 +12:00
end
2020-10-02 03:38:14 +13:00
```
## Connect your schema
### 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
2023-03-20 18:00:58 +13:00
plug AshGraphql.Plug
2020-10-10 14:16:40 +13:00
forward "/gql",
to: Absinthe.Plug,
2023-01-30 13:03:59 +13:00
init_opts: [schema: Helpdesk.Schema]
2020-10-02 03:38:14 +13:00
forward "/playground",
2020-10-10 14:16:40 +13:00
to: Absinthe.Plug.GraphiQL,
init_opts: [
2023-01-30 13:03:59 +13:00
schema: Helpdesk.Schema,
2020-10-10 14:16:40 +13:00
interface: :playground
]
2020-10-02 03:38:14 +13:00
```
### Using Phoenix
2022-09-07 10:24:02 +12:00
You will simply want to add some code to your router, like so.
2020-10-02 03:38:14 +13:00
You will also likely want to set up the "playground" for trying things out.
2020-08-14 10:55:34 +12:00
2020-10-02 03:38:14 +13:00
```elixir
2023-03-20 18:00:58 +13:00
pipeline :graphql do
plug AshGraphql.Plug
end
2020-10-02 03:38:14 +13:00
scope "/" do
2023-03-20 18:00:58 +13:00
pipe_through [:graphql]
2023-01-30 13:03:59 +13:00
forward "/gql", Absinthe.Plug, schema: Helpdesk.Schema
2020-10-02 03:38:14 +13:00
forward "/playground",
Absinthe.Plug.GraphiQL,
2023-01-30 13:03:59 +13:00
schema: Helpdesk.Schema,
2020-10-02 03:38:14 +13:00
interface: :playground
end
2020-08-14 10:55:34 +12:00
```
2020-10-02 03:38:14 +13:00
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.
2023-02-21 05:52:47 +13:00
## 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 )