Gaiia.Client (Gaiia v0.2.0)

HTTP client for the Gaiia GraphQL API.

A Gaiia.Client is a lightweight, immutable struct holding the endpoint, optional API key, custom headers, and pass-through options forwarded to Req.

Requests are POSTed to the endpoint with the key in the X-Gaiia-Api-Key header, as the API requires.

Configuration

Defaults can be supplied through application config:

config :gaiia,
  endpoint: "https://api.gaiia.com/api/v1",
  api_key: System.get_env("GAIIA_API_KEY")

Example

client = Gaiia.Client.new()

{:ok, %{"account" => account}} =
  Gaiia.Client.query(client, ~S"""
  query($id: GlobalID!) {
    account(id: $id) { id name }
  }
  """, %{"id" => "account_8rnXNuR5sKP5uNwoPL41Zp"})

Summary

Functions

default_endpoint()

The public Gaiia GraphQL endpoint, used when none is configured.

mutate(client, mutation, variables \\ %{}, opts \\ [])

Run a GraphQL mutation. Mechanically identical to query/4 — provided for readability at call sites.

new(opts \\ [])

Build a new client.

query(client, query, variables \\ %{}, opts \\ [])

Run a GraphQL query.

request(client, query, variables \\ %{}, opts \\ [])

Run a GraphQL operation and keep the transport metadata.

Types

t()

@type t() :: %Gaiia.Client{
  api_key: String.t() | nil,
  endpoint: String.t(),
  headers: [{String.t(), String.t()}],
  req_options: keyword(),
  timezone: String.t() | nil
}

Functions

default_endpoint()

@spec default_endpoint() :: String.t()

The public Gaiia GraphQL endpoint, used when none is configured.

mutate(client, mutation, variables \\ %{}, opts \\ [])

@spec mutate(t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Gaiia.Error.t()}

Run a GraphQL mutation. Mechanically identical to query/4 — provided for readability at call sites.

new(opts \\ [])

@spec new(keyword()) :: t()

Build a new client.

Options

:endpoint — GraphQL endpoint URL. Defaults to the :gaiia

               application env, then `default_endpoint/0`.

:api_key — API key sent in the X-Gaiia-Api-Key header.

               Defaults to the `:gaiia` application env. Without
               one, the API answers every operation with an
               `UNAUTHENTICATED` GraphQL error.

:timezone — IANA identifier (e.g. "America/Toronto") sent as

               `x-timezone`. Scheduling, availability, and
               work-order assignment operations resolve local day
               boundaries with it; browsers send it automatically,
               API integrations must set it. Defaults to the
               `:gaiia` application env.

:headers — Extra headers as [{name, value}].

:req_options — Keyword list of options forwarded to Req.request/1.

               Useful for testing (`:adapter`, `:plug`) and tuning
               (`:retry`, `:receive_timeout`, etc.).

query(client, query, variables \\ %{}, opts \\ [])

@spec query(t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Gaiia.Error.t()}

Run a GraphQL query.

Returns {:ok, data} on success, where data is the value of the data field in the GraphQL response. Returns {:error, %Gaiia.Error{}} on any failure mode.

Options

:operation_name — GraphQL operation name to send (operationName).
:timezone — IANA identifier sent as x-timezone, overriding the client's own. Scheduling, availability, and work-order assignment operations resolve local day boundaries with it.
:headers — extra headers for this call only, as [{name, value}].

request(client, query, variables \\ %{}, opts \\ [])

@spec request(t(), String.t(), map(), keyword()) ::
  {:ok, Gaiia.Response.t()} | {:error, Gaiia.Error.t()}

Run a GraphQL operation and keep the transport metadata.

Same options as query/4, but returns a Gaiia.Response holding the data, the HTTP status, the response headers, and the rate-limit budget the API reported. Use this to throttle bulk work before the API rejects it.