Graphlient Ruby Client

Graphlient is a Ruby client designed for consuming GraphQL-based APIs. It is built on top of the graphql-client gem but provides several improvements:

• Better default configurations.
• More consistent error handling.
• Uses the faraday HTTP client by default.

Instantiating a Graphlient::Client can be resource-intensive if it has to load a large schema file every time. To optimize this, instantiate a Graphlient::Schema once (e.g., in an initializer) and pass that instance into the schema: option when creating new clients.

# In an initializer
schema = Graphlient::Schema.new(
  'https://graphql.foo.com/graphql', 'lib/graphql_schema_foo.json'
)

# When creating clients
client = Graphlient::Client.new(
  'https://graphql.foo.com/graphql',
  schema: schema,
  headers: { 'Authorization' => 'Bearer 123' }
)

For better performance and following graphql-client recommendations, build queries as static members. Set allow_dynamic_queries: false in the client configuration, parse the query once into a constant, and then execute that constant.

module SWAPI
  Client = Graphlient::Client.new('https://test-graphql.biz/graphql', allow_dynamic_queries: false)

  InvoiceQuery = Client.parse do
    query(id: :int) do
      invoice(id: :id) do
        id
      end
    end
  end
end

# Execution
response = SWAPI::Client.execute(SWAPI::InvoiceQuery, id: 42)

Pass variables to queries or mutations by providing them as arguments to the query method. You can define types using symbols. Supported default scalars include :id, :boolean, :float, :int, and :string. Use ! for non-null types and [] for arrays.

# Using a String with variables
query = <<-GRAPHQL
  query($ids: [Int]) {
    invoices(ids: $ids) {
      id
    }
  }
GRAPHQL
variables = { ids: [42] }
client.query(query, variables)

# Using a block with variables
client.query(ids: [42]) do
  query(ids: [:int]) do
    invoices(ids: :ids) do
      id
    end
  end
end

When upgrading to version 0.4.0 or higher, ensure your environment uses Faraday >= 1.0.

Note a change in error handling: if a GraphQL request fails due to a server error, Graphlient now returns Graphlient::Errors::FaradayServerError instead of the previous Faraday::ServerError.

Apply directives using the _name convention. Any method starting with an underscore is treated as a directive (e.g., _skip becomes @skip). Directives can be applied to fields, fragment spreads, and inline fragments.

# On a field
client.query(skip_fee: :boolean!) do
  query(skip_fee: :skip_fee!) do
    invoice(id: :id) do
      feeInCents _skip(if: :skip_fee)
    end
  end
end

# On a fragment spread
spread :InvoiceFields, _skip(if: :skip_invoice)

# On an inline fragment
spread(_skip(if: :skip_drafts), on: :DraftInvoice) { draftId }

To reduce performance overhead and improve security, you can separate the parsing/validation step from the execution step. Use client.parse to return a GraphQL::Client::OperationDefinition, then pass that definition to client.execute along with your variables.

# 1. Parse (returns GraphQL::Client::OperationDefinition)
query_def = client.parse do
  query(ids: [:int]) do
    invoices(ids: :ids) do
      id
    end
  end
end

# 2. Execute (returns GraphQL::Client::Response)
client.execute(query_def, ids: [42])

Create a new instance of Graphlient::Client by providing a URL. You can optionally configure headers and http_options (such as read_timeout and write_timeout). The schema is automatically loaded and accessible via the .schema method.

client = Graphlient::Client.new('https://test-graphql.biz/graphql',
  headers: {
    'Authorization' => 'Bearer 123'
  },
  http_options: {
    read_timeout: 20,
    write_timeout: 30
  }
)

You can execute GraphQL queries or mutations using the query method. This method accepts either a raw GraphQL String or a Ruby block that uses a DSL to define the operation. Successful responses return an object where data is accessible via method chaining on the .data attribute.

# Using a String
response = client.query <<~GRAPHQL
  query {
    invoice(id: 10) {
      id
      total
    }
  }
GRAPHQL

# Using a block
response = client.query do
  query do
    invoice(id: 10) do
      id
      total
    end
  end
end

# Accessing data
puts response.data.invoice.id

To avoid making repeated requests to the GraphQL API to fetch the schema, you can cache it to a local JSON file using the schema_path option. When the schema changes on the server, call .schema.dump! to update the local file.

client = Graphlient::Client.new(url, schema_path: 'config/your_graphql_schema.json')
client.schema.dump! # Call this when the remote schema changes

To use Graphlient in your Ruby project, add the gem to your Gemfile.

gem 'graphlient'