AbsintheClient – GraphQL client with Subscriptions

Announcing AbsintheClient - A GraphQL client designed for Absinthe.

What is AbsintheClient?

AbsintheClient is a Req plugin to perform GraphQL operations, including subscriptions.

  • 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).

Here is an example straight from the docs using rickandmortyapi.com to fetch all the Cronenbergs:

req = Req.new(base_url: "https://rickandmortyapi.com") |> AbsintheClient.attach()

  graphql: {
    query ($name: String!) {
      characters(filter: {name: $name}) {
        results {
    %{name: "Cronenberg"}
  "characters" => %{
    "results" => [
      %{"name" => "Cronenberg Rick"},
      %{"name" => "Cronenberg Morty"}


AbsintheClient includes a custom adapter for performing operations over WebSockets, which is mostly useful for managing subscriptions.

Speaking of subscriptions, one killer feature in AbsintheClient is the ability to automatically re-establish subscriptions on disconnect/reconnect. When your WebSocket disconnects, whether due to network failure, rolling deployment, or an elusive third thing, when the socket reconnects AbsintheClient will automatically re-subscribe to any active subscriptions.

Let’s review a subscriptions example. In this scenario an Absinthe server has defined a subscription for leaving comments on repositories. We can create a subscription to listen for new comments:

client = Req.new(base_url: "http://localhost:4000") |> AbsintheClient.attach()
websocket = AbsintheClient.WebSocket.connect!(client, url: "/subscriptions/websocket")

gql =
  subscription RepoCommentSubscription($repository: Repository!){
    repoCommentSubscribe(repository: $repository){

variables = %{"repository" => "absinthe-graphql/absinthe"}

Req.request!(client, web_socket: web_socket, graphql: {gql, variables}).body
#=> %AbsintheClient.Subscription{}

When a change occurs, the server will publish a message with the subscription data:

#=> %AbsintheClient.WebSocket.Message{event: "subscription:data", payload: %{"data" => %{"repoCommentSubscribe" => %{"id" => 1, "commentary" => "Absinthe is great!"}}}

The Future

The initial release of AbsintheClient was just a necessary first step. We are embarking on an exciting new journey around GraphQL state management in Elixir, specifically in Phoenix LiveView. Over the next few weeks and months, expect to see more releases with tools for managing Absinthe socket state in the LiveView process, operation bindings with loading states, pagination, and much, much more!

For the GraphQL (not Absinthe) users– we are not leaving you out in the cold! Query and mutation operations work today for all GraphQL servers that support JSON POST requests. Support for other formats is planned. Subscriptions support is underway, too– we have made solid initial progress on a graphql-transport-ws adapter, too. It won’t provide all of the same guarantees as the Phoenix Channels implementation, but it will definitely support automatic re-subscription so stay tuned for those updates.

Getting involved

First and foremost, if you’re an Absinthe user we would love to get your feedback– do you see a use case for AbsintheClient? What kind of tools would you like to see in a client library? What should we focus on next?

Finally if you are remotely interested in improving the state of GraphQL client operations in Elixir, we would love to have your help! Several members of the CargoSense team have tackled this problem from different angles at different times and we would like to begin coordinating this effort around the AbsintheClient library.

Thanks for reading and happy gardening!


Hello Michael! Nice to see you :slight_smile:

Congratulations on the release! This is a much needed piece in the Elixir ecosystem, particularly now with how good LiveView is! It’s great to finally see a proper client for GraphQL APIs in Elixir system. I see a future where SPAs are replaced with LiveView+GraphQL based front-ends :smiley:

I still remember @benwilson512’s post from 2019 Anyone using a Phoenix LiveView Client to access a Phoenix Absinthe API? - #3 by benwilson512 where he had mentioned Absinthe.Client, although I presume this library only takes an inspiration from what you have at work given that Req 0.3 wasn’t released that long ago… :slight_smile:

This topic is also close to my heart, I cannot wait to dig deeper into it
and I’m happy to help :slight_smile:

At work, we’ve got an Elixir service that has to make few calls to GraphQL API
and I’ve dearly missed the pros of GraphQL! Our SPAs use Apollo and its tooling to
maximum extent(TS types, compilation, caching, etc.) but there wasn’t anything out there for Elixir apps. Given our Elixir service limited scope, we’ve just used Req with json:. And there’s another reason why I’m delighted something is moving in this area.

Last year I’ve started making some steps into a proper GraphQL Client. I wanted something easy to use in LiveBook to create some demos and to try replacing React+Apollo SPA with LiveView, keeping GraphQL API from Rails app unchanged.

I really wanted support for compile time validation of queries, subscriptions and caching (similar to Apollo), and on the last piece I struggled the most and then got life in a way before I had something to release.

My approach was to basically reuse as much as possible from Absinthe. Based on SDLC (or Introspection query result) I’ve created Absinthe schema, hijacked the pipeline for running queries against the schema and added additional steps to
make the query against remote API, all resolvers were no-op. :smile:

All queries were in ~g sigil and queries inside it would be validated against the schema.

When I got to subscriptions, I’ve followed graphql-ws too!
With some glue on top to make it work both with Apollo based GraphQL APIs and
Absinthe Elixir API in case the remote service is in Elixir too via slipstream.

I’ve to say, the approach with hijacking Absinthe’s pipeline worked nicely and saved me a lot of time,
but when I got to caching… this when things very interesting.
It was had for me to get nice DX with websocket based queries, subscriptions and LiveView.
That was many months ago, since then life got in a way and I put the project on hold :see_no_evil:

Congratulations again and I’ll probably come back in issue tracker :slight_smile: