# AbsintheClient

[![Hex pm](](

A GraphQL client designed for Elixir [Absinthe][absinthe].

## Features

- Performs `query` and `mutation` operations via JSON POST requests.

- Performs `subscription` operations over WebSockets ([Absinthe Phoenix][absinthe_phoenix]).

- Automatically re-establishes subscriptions on socket disconnect/reconnect.

- Supports virtually all [`Req.request/1`][request] options, notably:

  - Bearer authentication (via the [`auth`][req_auth] step).

  - Retries on errors (via the [`retry`][req_retry] step).

## Usage

The fastest way to use AbsintheClient is with [`Mix.install/2`][install] (requires Elixir v1.12+):

  {:absinthe_client, "~> 0.1.0"}
]) "")
|> AbsintheClient.attach()
|>!(graphql: "query { character(id: 1) { name } }").body
#=> %{"data" => "character" => %{"name" => "Rick Sanchez"}}}

If you want to use AbsintheClient in a Mix project, you can add the above dependency to your list of dependencies in `mix.exs`.

AbsintheClient is intended to be used by building a common client
struct with a `base_url` and re-using it on each operation:

base_url = ""
req = base_url) |> AbsintheClient.attach()!(req, graphql: "query { character(id: 2) { name } }").body
#=> %{"data" => "character" => %{"name" => "Morty Smith"}}}

Refer to [`AbsintheClient`][client] for more information on available options.

### Subscriptions (WebSockets)

AbsintheClient supports WebSocket operations via a custom Req adapter.
You must first start the WebSocket connection, then you make the
request with [`Req.request/2`][request2]:

base_url = "https://my-absinthe-server"
req = base_url) |> AbsintheClient.attach()

ws = AbsintheClient.WebSocket.connect!(req, url: "/socket/websocket")

Req.request!(req, web_socket: ws, graphql: "subscription ...").body
#=> %AbsintheClient.WebSocket.Subscription{}

Note that although AbsintheClient _can_ use the `:web_socket` option
to execute all GraphQL operation types, in most cases it should
continue to use HTTP for queries and mutations. This is because
queries and mutations do not require a stateful or long-lived
connection and depending on the number of concurrent requests it may
be more efficient to avoid blocking the socket for those operations.

Refer to [`AbsintheClient.attach/2`][attach2] for more information on handling subscriptions.

### Authentication

AbsintheClient supports Bearer authentication for HTTP and WebSocket operations:

base_url = "https://my-absinthe-server"
auth = {:bearer, "token"}
req = base_url, auth: auth) |> AbsintheClient.attach()

# ?Authentication=Bearer+token will be sent on the connect request.
ws = AbsintheClient.WebSocket.connect(req, url: "/socket/websocket")

If you use your client to authenticate then you can set `:auth` by
merging options:

base_url = "https://my-absinthe-server"
req = base_url) |> AbsintheClient.attach()

doc = "mutation { login($input) { token } }"
graphql = {doc, %{user: "root", password: ""}}
token =!(req, graphql: graphql).body["data"]["login"]["token"]
req = Req.Request.merge_options(req, auth: {:bearer, token})

## Why AbsintheClient?

There is another popular GraphQL library for Elixir called [Neuron][neuron].
So why choose AbsintheClient? In short, you might use AbsintheClient if you
need Absinthe Phoenix subscription support, if you want to avoid global
configuration, and if you want to declaratively build your requests. For

|                    | AbsintheClient                                      | Neuron                                      |
| ------------------ | --------------------------------------------------- | ------------------------------------------- |
| **HTTP**           | [Req][req], [Finch][finch]                          | [HTTPoison][httpoison], [hackney][hackney]  |
| **WebSockets**     | [Slipstream][slipstream], [Mint.WebSocket][mint_ws] | n/a                                         |
| **Configuration**  | `%Req.Request{}`                                    | Application and Process-based               |
| **Request style**  | Declarative, builds a struct                        | Imperative, invokes a function              |

## Acknowledgements

AbsintheClient is built on top of the [Req][req] requests library for HTTP and the [Slipstream][slipstream] WebSocket library for Phoenix Channels.

## License

MIT license. Copyright (c) 2019 Michael A. Crumm Jr., Ben Wilson