absinthe v1.1.5 Absinthe.Adapter behaviour

Absinthe supports an adapter mechanism that allows developers to define their schema using one code convention (eg, snake_cased fields and arguments), but accept query documents and return results (including names in errors) in another (eg, camelCase).

Adapters aren’t a part of GraphQL, but a utility that Absinthe adds so that both client and server can use use conventions most natural to them.

Absinthe ships with two adapters:

Absinthe.Adapter.LanguageConventions, which expects schemas to be defined in snake_case (the standard Elixir convention), translating to/from camelCase for incoming query documents and outgoing results. (This is the default as of v0.3.)
Absinthe.Adapter.Passthrough, which is a no-op adapter and makes no modifications. (Note at the current time this does not support introspection if you’re using camelized conventions).

To set an adapter, you can set an application configuration value:

config :absinthe,
  adapter: Absinthe.Adapter.TheAdapterName

Or, you can provide it as an option to Absinthe.run/3:

Absinthe.run(query, MyApp.Schema,
           adapter: Absinthe.Adapter.TheAdapterName)

Notably, this means you’re able to switch adapters on case-by-case basis. In a Phoenix application, this means you could even support using different adapters for different clients.

A custom adapter module must merely implement the Absinthe.Adapter protocol, in many cases with use Absinthe.Adapter and only overriding the desired functions.

Writing Your Own

Considering the default implementation of the callbacks handle traversing ASTs for you, there’s a good chance all you may need to implement in your adapter is to_internal_name/2 and to_external_name/2.

Check out Absinthe.Adapter.LanguageConventions for a good example.

Note that types that are defined external to your application (including the introspection types) may not be compatible if you’re using a different adapter.

Summary

Types

role_t()

The lexical role of a name within the document/schema

t()

Callbacks

adapt(arg0, arg1)

Convert an AST node to/from a representation

dump_results(arg0)

Convert the canonical (internal) results to the output (external) representation

format_error(arg0)

format_error(arg0, list)

Format an error using value for name located at the provided line/column locations

load_document(arg0)

Convert the incoming (external) parsed document to the canonical (internal) representation that matches the schema

to_external_name(binary, role_t)

Convert a name from an internal name to an external name

to_internal_name(binary, role_t)

Convert a name from an external name to an internal name

Types

role_t ::
  :operation |
  :field |
  :argument |
  :result |
  :type |
  :directive

The lexical role of a name within the document/schema.

t :: atom

Callbacks

adapt(arg0, arg1)

Specs

adapt(Absinthe.Language.t, :load | :dump) :: Absinthe.Language.t

Convert an AST node to/from a representation.

Called by load_document/1.

Examples

def adapt(%{definitions: definitions} = document, :load) do
  %{document | definitions: definitions |> Enum.map(&your_custom_loader/1)}
end

dump_results(arg0)

Specs

dump_results(Absinthe.Execution.result_t) :: any

Convert the canonical (internal) results to the output (external) representation.

Examples

def dump_results(%{data: data} = results) do
  %{results | data: your_custom_transformation(data)}
end

format_error(arg0)

Specs

format_error(Absinthe.Execution.error_info_t) :: Absinthe.Execution.error_t

format_error(arg0, list)

Specs

format_error(Absinthe.Execution.error_info_t, [Absinthe.Execution.error_location_t]) :: Absinthe.Execution.error_t

Format an error using value for name located at the provided line/column locations.

Examples

Here’s what the default implementation does:

iex> format_error(%{name: "foo", role: :field, value: &"missing value '#{&1}'"}, [%{line: 2, column: 4}])
%{message: "missing value `foo'", locations: [%{line: 2, column: 4}]}

iex> format_error(%{name: "foo", role: :field, value: "missing value"}, [%{line: 2, column: 4}])
%{message: "Field `foo': missing value", locations: [%{line: 2, column: 4}]}

# Without locations
iex> format_error(%{name: "foo", role: :field, value: "missing value"})
%{message: "Field `foo': missing value"}

load_document(arg0)

Specs

load_document(Absinthe.Language.Document.t) :: Absinthe.Language.Document.t

Convert the incoming (external) parsed document to the canonical (internal) representation that matches the schema.

Examples

def load_document(%{definitions: definitions} = document) do
  %{document | definitions: definitions |> Enum.map(&your_custom_transformation/1)}
end

to_external_name(binary, role_t)

Specs

to_external_name(binary, role_t) :: binary

Convert a name from an internal name to an external name.

Examples

Remove the role-prefix (the inverse of what we did in to_internal_name/2 above):

def to_external_name(internal_name, role) do
  internal_name
  |> String.replace(~r/^#{role}_/, "")
end

to_internal_name(binary, role_t)

Specs

to_internal_name(binary, role_t) :: binary

Convert a name from an external name to an internal name.

Examples

Prefix all names with their role, just for fun!

def to_internal_name(external_name, role) do
  role_name = role |> to_string
  role_name <> "_" <> external_name
end