absinthe v1.4.0-beta.1 Absinthe View Source
Documentation for the Absinthe package, a toolkit for building GraphQL APIs with Elixir.
Absinthe aims to handle authoring GraphQL API schemas — then supporting their introspection, validation, and execution according to the GraphQL specification.
This documentation covers specific details of the Absinthe API. For guides, tutorials, GraphQL, and community information, see the Absinthe Website.
Building HTTP APIs
IMPORTANT: For HTTP, you’ll probably want to use
AbsinthePlug instead of executing
GraphQL query documents yourself. Absinthe doesn’t know or care about HTTP,
so keep that in mind while reading through the documentation. While you’ll
be building schemas just as in the examples here, the actual calls to
Absinthe.run/3
and its friends are best left to
AbsinthePlug if you’re providing an
HTTP API.
Ecosystem
Here are some additional projects you’re likely to use in conjunction with Absinthe to launch an API:
- Ecto - a language integrated query and database wrapper.
- Phoenix - the Phoenix web framework.
- Plug - a specification and conveniences for composable modules in between web applications.
- Poison - JSON serialization.
GraphQL Basics
For background on GraphQL, please visit the GraphQL website.
GraphQL using Absinthe
The first thing you need to do is define a schema, we do this
by using Absinthe.Schema
.
For details on the macros available to build a schema, see
Absinthe.Schema.Notation
Here we’ll build a basic schema that defines one query field; a
way to retrieve the data for an item
, given an id
. Users of
the API can then decide what fields of the item
they’d like
returned.
defmodule App.Schema do
use Absinthe.Schema
@fake_db %{
"foo" => %{id: "foo", name: "Foo", value: 4},
"bar" => %{id: "bar", name: "Bar", value: 5}
}
query do
@desc "Get an item by ID"
field :item, type: :item do
@desc "The ID of the item"
arg :id, :id
resolve fn %{id: id}, _ ->
{:ok, Map.get(@fake_db, id)}
end
end
end
@desc "A valuable item"
object :item do
field :id, :id
@desc "The item's name"
field :name, :string
@desc "Recently appraised value"
field :value, :integer
end
end
Now we’ll execute a query document against it with
run/2
or run/3
(which return tuples), or their exception-raising
equivalents, run!/2
and run!/3
.
Let’s get the name
of an item
with id
"foo"
:
"""
{
item(id: "foo") {
name
}
}
"""
|> Absinthe.run(App.Schema)
Results are returned in a tuple, and are maps with :data
and/or :errors
keys, suitable for serialization
back to the client.
{:ok, %{data: %{"name" => "Foo"}}}
You can also provide values for variables defined in the query document (supporting, eg, values passed as query string parameters):
"""
query GetItemById($id: ID) {
item(id: $id) {
name
}
}
"""
|> Absinthe.run(App.Schema, variables: %{"id" => params[:item_id]})
The result, if params[:item_id]
was "foo"
, would be the same:
{:ok, %{data: %{"name" => "Foo"}}}
run!/2
and run!/3
operate similarly, except they will raise
Absinthe.SytaxError
and Absinthe.ExecutionError
if they cannot
parse/execute the document.
Link to this section Summary
Functions
Evaluates a query document against a schema, with options
Evaluates a query document against a schema, without options
Link to this section Types
result_error_t :: %{message: String.t} | %{message: String.t, locations: [%{line: integer, column: integer}]}
result_selection_t() :: %{optional(String.t) => nil | integer | float | boolean | binary | atom | result_selection_t}
result_t :: %{data: nil | result_selection_t} | %{data: nil | result_selection_t, errors: [result_error_t]} | %{errors: [result_error_t]}
run_opts() :: [context: %{}, adapter: Absinthe.Adapter.t, root_value: term, operation_name: String.t, analyze_complexity: boolean, max_complexity: non_neg_integer | :infinity]
Link to this section Functions
run(binary | Absinthe.Language.Source.t | Absinthe.Language.Document.t, Absinthe.Schema.t, run_opts) :: {:ok, result_t} | {:error, String.t}
Evaluates a query document against a schema, with options.
Options
:adapter
- The name of the adapter to use. See theAbsinthe.Adapter
behaviour and theAbsinthe.Adapter.Passthrough
andAbsinthe.Adapter.LanguageConventions
modules that implement it. (Absinthe.Adapter.LanguageConventions
is the default value for this option.):operation_name
- If more than one operation is present in the provided query document, this must be provided to select which operation to execute.:variables
- A map of provided variable values to be used when filling in arguments in the provided query document.:context
-> A map of the execution context.:root_value
-> A root value to use as the source for toplevel fields.:analyze_complexity
-> Whether to analyze the complexity before executing an operation.:max_complexity
-> An integer (or:infinity
) for the maximum allowed complexity for the operation being executed.
Examples
"""
query GetItemById($id: ID) {
item(id: $id) {
name
}
}
"""
|> Absinthe.run(App.Schema, variables: %{"id" => params[:item_id]})
See the Absinthe
module documentation for more examples.
run!(binary | Absinthe.Language.Source.t | Absinthe.Language.Document.t, Absinthe.Schema.t, Keyword.t) :: result_t | no_return
Evaluates a query document against a schema, without options.
Options
See run/3
for the available options.