GQLi - GraphQL Client for humans

GQLi is a DSL (Domain Specific Language) to consume GraphQL APIs.

DISCLAIMER:

This gem is in stable state and will be updated with more features. You can start using it for your respective projects, although there is no support available from Contentful.

This gem is not covered under the Contentful SLAs.

Users are free to create Github issues and collaborate.

Installation

Install it via the command line:

gem install gqli

Or add it to your Gemfile:

gem 'gqli'

Usage

Creating a GraphQL Client

For the examples throughout this README, we'll be using the Contentful and Github GraphQL APIs, for which we have factory methods. Therefore, here's the initialization code required for both of them:

require 'gqli'

# Creating a Contentful GraphQL Client
SPACE_ID = 'cfexampleapi'
CF_ACCESS_TOKEN = 'b4c0n73n7fu1'
CONTENTFUL_GQL = GQLi::Contentful.create(SPACE_ID, CF_ACCESS_TOKEN)

# Creating a Github GraphQL Client
GITHUB_ACCESS_TOKEN = ENV['GITHUB_TOKEN']
GITHUB_GQL = GQLi::Github.create(GITHUB_ACCESS_TOKEN)

Note: Please feel free to contribute factories for your favorite GraphQL services.

For creating a custom GraphQL client:

require 'gqli'

# Create a custom client
GQL_CLIENT = GQLi::Client.new(
  "https://graphql.yourservice.com",
  headers: {
    "Authorization" => "Bearer AUTH_TOKEN"
  }
)

Creating a Query

Queries are the way to request data from a GraphQL API. This gem provides a simple DSL to create your own queries.

The query operator is GQLi::DSL.query.

# Query to fetch the usernames for the first 10 watchers of the first 10 repositories I belong to
WatchersQuery = GQLi::DSL.query {
  viewer {
    login
    repositories(first: 10) {
      edges {
        node {
          nameWithOwner
          watchers(first: 10) {
            edges {
              node {
                login
              }
            }
          }
        }
      }
    }
  }
}

Divide and conquer - using Fragments

In order to reuse parts of queries, we can split chunks of our queries into Fragments.

The fragment operator is GQLi::DSL.fragment.

To include fragments within other nodes, use the ___ operator as shown below.

To do type matching, use the __on operator as shown below.

# Base fragment that will be reused for all Cat queries.
CatBase = GQLi::DSL.fragment('CatBase', 'Cat') {
  name
  likes
  lives
}

CatBestFriend = GQLi::DSL.fragment('CatBestFriend', 'Cat') {
  bestFriend {
    # Here, because `bestFriend` is polimorphic in our GraphQL API,
    # we need to explicitly state for which Type we want to include our fragment.
    # To do a type match, instead of GraphQLs `... on SomeType` we do `__on('SomeType')`.
    __on('Cat') {
      # To include a fragment, instead of GraphQLs `...`, we use `___`.
      ___ CatBase
    }
  }
}

# A fragment reusing multiple fragments
CatImportantFields = GQLi::DSL.fragment('CatImportantFields', 'Cat') {
  ___ CatBase
  ___ CatBestFriend
}

# A fragment used to define a query, alongside other regular fields.
CatQuery = GQLi::DSL.query {
  catCollection(limit: 1) {
    items {
      ___ CatImportantFields
      image {
        url
      }
    }
  }
}

Executing the queries

To execute the queries, you need to pass a Query object to the client's #execute method. This will return a Response object which contains the data and the query executed.

For example:

response = CONTENTFUL_GQL.execute(CatQuery)

puts "Query sent:"
puts response.query.to_gql

puts
puts "Response received"
response.data.catCollection.items.each do |c|
  puts "Name:    #{c.name}"
  puts "Likes:   #{c.likes.join(", ")}"
  puts "Lives #: #{c.lives}"
  c.bestFriend.tap do |bf|
    puts "Best Friend:"
    puts "\tName:    #{bf.name}"
    puts "\tLikes:   #{bf.likes.join(", ")}"
    puts "\tLives #: #{bf.lives}"
  end
end

The output is:

Query sent:
query {
  catCollection(limit: 1) {
    items {
      name
      likes
      lives
      bestFriend {
        ... on Cat {
          name
          likes
          lives
        }
      }
      image {
        url
      }
    }
  }
}

Response received
Name:    Happy Cat
Likes:   cheezburger
Lives #: 1
Best Friend:
	Name:    Nyan Cat
	Likes:   rainbows, fish
	Lives #: 1337

Schema Introspection and Validation

By default this library will fetch and cache a copy of the GraphQL Schema for any API you create a client for.

This schema is used for query validation before running queries against the APIs. In case a query is invalid for the given schema, an exception will be raised.

To disable schema caching completely, when you initialize your client, send validate_query: false.

Queries executed using the #execute method on the client will be validated before executing the request if the option is set to true (which it is by default).

To avoid validating a query, you can use #execute! instead.

To validate the query outside of the scope of an HTTP request, you can use MY_CLIENT.schema.valid?(query).

Embedding the DSL in your classes

If you want to avoid the need for prepending all GQLi DSL's calls with GQLi::DSL., then you can extend and/or include the module within your own classes. When using extend, you will have access to the DSL at a class level. When using include you will have access to the DSL at an object level.

class ContentfulClient
  extend GQLi::DSL # Makes DSL available at a class level
  include GQLi::DSL # Makes DSL available at an object level

  SPACE_ID = 'cfexampleapi'
  ACCESS_TOKEN = 'b4c0n73n7fu1'
  CONTENTFUL_GQL = GQLi::Client.new(
    "https://graphql.contentful.com/content/v1/spaces/#{SPACE_ID}",
    headers: { "Authorization" => "Bearer #{ACCESS_TOKEN}" }
  )

  CatBase = fragment('CatBase', 'Cat') {
    name
    likes
    lives
  }

  CatBestFriend = fragment('CatBestFriend', 'Cat') {
    bestFriend {
      __on('Cat') {
        ___ CatBase
      }
    }
  }

  CatImportantFields = fragment('CatImportantFields', 'Cat') {
    ___ CatBase
    ___ CatBestFriend
  }

  def cats(limit)
    CONTENTFUL_GQL.execute(
      query {
        catCollection(limit: limit) {
          items {
            ___ CatImportantFields
            image {
              url
            }
          }
        }
      }
    )
  end
end

response = ContentfulClient.new.cats(5)

Dealing with name collisions

By defining queries via a DSL, you may sometimes find that the fields you query for are also the names of built-in methods or reserved keywords of the language.

To avoid collisions you can use the __node helper, for example:

query = GQLi::DSL.query {
  catCollection {
    items {
      sys {
        __node('id')
      }
    }
  }
}

The helper method __node, can also receive arguments and have children nodes as expected from any other node declaration, for example:

query = GQLi::DSL.query {
  __node('catCollection', limit: 5) {
    items {
      name
    }
  }
}

Directives

In GraphQL, nodes can be selectively included or removed by the usage of directives, there are 2 directives available for the querying specification to do this: @include and @skip.

query = GQLi::DSL.query {
  someNode(:@include => {if: object.includes_some_node?})
}

This will get transformed to:

query {
  someNode @include(if: true) # or false
}

This behaviour is equivalent to using native Ruby to include/exclude a field from the query:

query = GQLi::DSL.query {
  someNode if object.includes_some_node?
}

The difference is that by using the native implementation, in case of the condition not being met, the node will be completely not included in the outgoing query.

Enums

Enums are a list of predefined values that are defined on the type system level. Since Ruby doesn't have built-in Enums that can be translated directly into GraphQL Enums, we created the __enum helper that you can use within your queries to transform your values into an Enum value.

query = GQLi::DSL.query {
  catCollection(order: __enum('lives_ASC')) {
    items {
      name
    }
  }
}

This will render to:

query {
  catCollection(order: lives_ASC) {
    items {
      name
    }
  }
}

Aliases

There may be times where it is useful to have parts of the query aliased, for example, when querying for pinned and unpinned articles for a news site.

This can be accomplished as follows:

ArticleFragment = GQLi::DSL.fragment('ArticleFragment', 'ArticleCollection') {
  items {
    title
    description
    heroImage {
      url
    }
  }
}

query = GQLi::DSL.query {
  __node('pinned: articleCollection', where: {
    sys: { id_in: ['articleID'] }
  }) {
    ___ ArticleFragment
  }
  __node('unpinned: articleCollection', where: {
    sys: { id_not_in: ['articleID'] }
  }) {
    ___ ArticleFragment
  }
}

Get involved

We appreciate any help on our repositories.

License

This repository is published under the MIT license.

Code of Conduct

We want to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers.

Read our full Code of Conduct.

gqli

Development

Runtime