AbsintheClient

A GraphQL client designed for Elixir Absinthe.

Features

• Performs query and mutation operations via JSON POST requests.

• Performs subscription operations over WebSockets (Absinthe Phoenix).

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

• Supports virtually all Req.request/1 options, notably:

  • Bearer authentication (via the auth step).

  • Retries on errors (via the retry step).

Usage

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

Mix.install([
  {:absinthe_client, "~> 0.1.0"}
])

Req.new(base_url: "https://rickandmortyapi.com")
|> AbsintheClient.attach()
|> Req.post!(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 = "https://rickandmortyapi.com"
req = Req.new(base_url: base_url) |> AbsintheClient.attach()

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

Refer to AbsintheClient 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:

base_url = "https://my-absinthe-server"
req = Req.new(base_url: 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 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 = Req.new(base_url: 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 = Req.new(base_url: base_url) |> AbsintheClient.attach()

doc = "mutation { login($input) { token } }"
graphql = {doc, %{user: "root", password: ""}}
token = Req.post!(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. 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 comparison:

	AbsintheClient	Neuron
HTTP	Req, Finch	HTTPoison, hackney
WebSockets	Slipstream, Mint.WebSocket	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 requests library for HTTP and the Slipstream WebSocket library for Phoenix Channels.

License

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