View Source AbsintheClient
A GraphQL client designed for Elixir Absinthe.
features
Features
Performs
query
andmutation
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:
usage
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
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
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
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
Acknowledgements
AbsintheClient is built on top of the Req requests library for HTTP and the Slipstream WebSocket library for Phoenix Channels.
license
License
MIT license. Copyright (c) 2019 Michael A. Crumm Jr., Ben Wilson