Improved GraphQL client

README.md

@@ -346,15 +346,18 @@ gem install shopify_api_console
 
 ## GraphQL
 
-This library also supports Shopify's new [GraphQL API](https://help.shopify.com/api/graphql-admin-api)
-via a dependency on the [graphql-client](https://github.com/github/graphql-client) gem.
+Note: the GraphQL client has improved and changed in version 9.0. See the [client documentation](docs/graphql.md)
+for full usage details and a [migration guide](docs/graphql.md#migration-guide).
+
+This library also supports Shopify's [GraphQL Admin API](https://help.shopify.com/api/graphql-admin-api)
+via integration with the [graphql-client](https://github.com/github/graphql-client) gem.
 The authentication process (steps 1-5 under [Getting Started](#getting-started))
-is identical. Once your session is activated, simply construct a new graphql
-client and use `parse` and `query` as defined by
+is identical. Once your session is activated, simply access the GraphQL client
+and use `parse` and `query` as defined by
 [graphql-client](https://github.com/github/graphql-client#defining-queries).
 
 ```ruby
-client = ShopifyAPI::GraphQL.new
+client = ShopifyAPI::GraphQL.client
 
 SHOP_NAME_QUERY = client.parse <<-'GRAPHQL'
   {
@@ -368,6 +371,8 @@ result = client.query(SHOP_NAME_QUERY)
 result.data.shop.name
 ```
 
+[GraphQL client documentation](docs/graphql.md)
+
 ## Threadsafety
 
 ActiveResource is threadsafe as of version 4.1 (which works with Rails 4.x and above).

docs/graphql.md

@@ -0,0 +1,191 @@
+# GraphQL client
+
+The `shopify_api` gem includes a full featured GraphQL client to interact with
+Shopify's [GraphQL Admin API](https://help.shopify.com/en/api/graphql-admin-api).
+GitHub's [graphql-client](https://github.com/github/graphql-client) is used as
+the underlying client and this library integrates it with our existing
+session, authentication, and API versioning features.
+
+## Example
+
+```ruby
+client = ShopifyAPI::GraphQL.client
+
+SHOP_NAME_QUERY = client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = client.query(SHOP_NAME_QUERY)
+result.data.shop.name
+```
+
+* [Getting started](#getting-started)
+* [Rails integration](#rails-integration)
+* [API versioning](#api-versioning)
+* [Initialization process](#initialization-process)
+* [Migration guide](#migration-guide)
+
+## Getting started
+
+1. [Dump the schema](#dump-the-schema)
+2. [Configure session/authencation](#sessions-and-authentication)
+3. [Make queries](#make-queries)
+
+### Dump the schema
+One of the main benefits of GraphQL is its [schema and type system](https://graphql.org/learn/schema/)
+which enables tools like graphql-client to ensure your queries are valid in development.
+
+So the first step in making GraphQL queries is having a local JSON file of Shopify's Admin schema.
+This gem provides a `shopify_api:graphql:dump` Rake task to make it as easy as possible:
+
+```bash
+$ rake shopify_api:graphql:dump SHOP_URL="https://API_KEY:PASSWORD@SHOP_NAME.myshopify.com" API_VERSION=2020-01
+```
+
+If successful `db/shopify_graphql_schemas/2020-01.json` will be created.
+
+You can either use private app authentication or an OAuth access token. Run `rake shopify_api:graphql:dump`
+to see full usage details.
+
+If you're using shopify_api in a Rails app, the default location for schema files is `db/shopify_graphql_schemas`.
+For non-Rails applications, the default is `shopify_graphql_schemas` in your project root.
+
+The schema path location can be changed via `ShopifyAPI::GraphQL.schema_location`:
+
+```ruby
+ShopifyAPI::GraphQL.schema_location = 'assets/schemas'
+```
+
+#### Updating schemas
+Each time you want to use a new API version, or update an existing one
+(such as the `unstable` version), simply run the Rake task again to overwrite the file.
+
+### Sessions and authentication
+The GraphQL client is designed to be integrated with the rest of shopify_api so
+all its features such as sessions, authentication, and API versioning work the
+exact same.
+
+If you've already been using the shopify_api gem in your application to make
+REST API calls then no other configuration is necessary.
+
+Steps 1-5 of our main [Getting started](https://github.com/Shopify/shopify_api#getting-started)
+section still apply for the GraphQL client as well.
+
+### Make queries
+Now that you've dumped a schema file and configured an authenticated session, you can make GraphQL API requests.
+graphql-client encourages all queries to be defined statically as constants:
+
+```ruby
+SHOP_NAME_QUERY = ShopifyAPI::GraphQL.client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = ShopifyAPI::GraphQL.client.query(SHOP_NAME_QUERY)
+result.data.shop.name
+```
+
+But we've also enabled its `allow_dynamic_queries` option if you prefer:
+
+```ruby
+query = ShopifyAPI::GraphQL.client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = ShopifyAPI::GraphQL.client.query(query)
+result.data.shop.name
+```
+
+See the [graphql-client documentation](https://github.com/github/graphql-client#defining-queries)
+for more details on defining and executing queries.
+
+## Rails integration
+`ShopifyAPI::GraphQL` integrates with Rails to automatically do the following:
+
+* load the `shopify_api:graphql:dump` Rake task
+* set the `schema_location` to be in the `db` directory in your Rails root
+* initialize clients in the Rails app initializer phase
+
+## API versioning
+`ShopifyAPI::GraphQL` is version aware and lets you easily make queries to multiple
+API versions through version specific clients if need be.
+
+If you have multiple clients and need to be explicit you can specify the version parameter:
+
+```ruby
+ShopifyAPI::GraphQL.client # defaults to the client using ShopifyAPI::Base.api_version
+ShopifyAPI::GraphQL.client('unstable')
+```
+
+## Initialization process
+`ShopifyAPI::GraphQL` is a thin integration layer which initializes `GraphQL::Client`s
+from local schema files.
+
+`ShopifyAPI::GraphQL.initialize_clients` scans `ShopifyAPI::GraphQL.schema_location`
+and creates a client for each version specific schema file found.
+
+This happens automatically in a Rails application due to our [integration](#rails-integration).
+For non-Rails applications, ensure you call `ShopifyAPI::GraphQL.initialize_clients`
+during your boot process.
+
+The goal is to have all clients created at boot so there's no schema loading,
+parsing, or client instantiation done during runtime when your app serves a request.
+
+## Migration guide
+Prior to shopify_api v9.0 the GraphQL client implementation was limited and almost
+unusable due to the client making dynamic introspection queries to Shopify's API.
+This was not only very slow but also led to unbounded memory growth.
+
+There are two steps to migrate to the new client:
+1. [Dump a local schema file](#dump-the-schema)
+2. [Migrate `client` usage](#migrate-usage)
+
+### Migrate usage
+
+Previously a client was initialized with `ShopifyAPI::GraphQL.new`:
+```ruby
+client = ShopifyAPI::GraphQL.new
+
+SHOP_NAME_QUERY = client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = client.query(SHOP_NAME_QUERY)
+result.data.shop.name
+```
+
+Now there's no need to initialize a client so all references to
+`ShopifyAPI::GraphQL.new` should be removed and instead the client is called
+via `ShopifyAPI::GraphQL.client`:
+
+```ruby
+client = ShopifyAPI::GraphQL.client
+
+SHOP_NAME_QUERY = client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = client.query(SHOP_NAME_QUERY)
+result.data.shop.name
+```
+
+See [making queries](#making-queries) for more usage details.

lib/shopify_api.rb

@@ -23,6 +23,8 @@ module ShopifyAPI
 require 'shopify_api/message_enricher'
 require 'shopify_api/connection'
 require 'shopify_api/pagination_link_headers'
+require 'shopify_api/graphql'
+require 'shopify_api/graphql/railtie' if defined?(Rails)
 
 if ShopifyAPI::Base.respond_to?(:connection_class)
   ShopifyAPI::Base.connection_class = ShopifyAPI::Connection

lib/shopify_api/api_version.rb

@@ -5,8 +5,8 @@ class UnknownVersion < StandardError; end
     class ApiVersionNotSetError < StandardError; end
     include Comparable
 
-    HANDLE_FORMAT = /^\d{4}-\d{2}$/.freeze
     UNSTABLE_HANDLE = 'unstable'
+    HANDLE_FORMAT = /((\d{4}-\d{2})|#{UNSTABLE_HANDLE})/.freeze
     UNSTABLE_AS_DATE = Time.utc(3000, 1, 1)
     API_PREFIX = '/admin/api/'
     LOOKUP_MODES = [:raise_on_unknown, :define_on_unknown].freeze

lib/shopify_api/graphql.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+require 'graphql/client'
+require 'shopify_api/graphql/http_client'
+
+module ShopifyAPI
+  module GraphQL
+    DEFAULT_SCHEMA_LOCATION_PATH = Pathname('shopify_graphql_schemas')
+
+    InvalidSchema = Class.new(StandardError)
+    InvalidClient = Class.new(StandardError)
+
+    class << self
+      delegate :parse, :query, to: :client
+
+      def client(api_version = ShopifyAPI::Base.api_version.handle)
+        initialize_client_cache
+        cached_client = @_client_cache[api_version]
+
+        if cached_client
+          cached_client
+        else
+          schema_file = schema_location.join("#{api_version}.json")
+
+          if !schema_file.exist?
+            raise InvalidClient, <<~MSG
+              Client for API version #{api_version} does not exist because no schema file exists at `#{schema_file}`.
+
+              To dump the schema file, use the `rake shopify_api:graphql:dump` task.
+            MSG
+          else
+            puts '[WARNING] Client was not pre-initialized. Ensure `ShopifyAPI::GraphQL.initialize_clients` is called during app initialization.'
+            initialize_clients
+            @_client_cache[api_version]
+          end
+        end
+      end
+
+      def clear_clients
+        @_client_cache = {}
+      end
+
+      def initialize_clients
+        initialize_client_cache
+
+        Dir.glob(schema_location.join("*.json")).each do |schema_file|
+          schema_file = Pathname(schema_file)
+          matches = schema_file.basename.to_s.match(/^#{ShopifyAPI::ApiVersion::HANDLE_FORMAT}\.json$/)
+
+          if matches
+            api_version = ShopifyAPI::ApiVersion.new(handle: matches[1])
+          else
+            raise InvalidSchema, "Invalid schema file name `#{schema_file}`. Does not match format of: `<version>.json`."
+          end
+
+          schema = ::GraphQL::Client.load_schema(schema_file.to_s)
+          client = ::GraphQL::Client.new(schema: schema, execute: HTTPClient.new(api_version)).tap do |c|
+            c.allow_dynamic_queries = true
+          end
+
+          @_client_cache[api_version.handle] = client
+        end
+      end
+
+      def schema_location
+        @schema_location || DEFAULT_SCHEMA_LOCATION_PATH
+      end
+
+      def schema_location=(path)
+        @schema_location = Pathname(path)
+      end
+
+      private
+
+      def initialize_client_cache
+        @_client_cache ||= {}
+      end
+    end
+  end
+end

lib/shopify_api/graphql/http_client.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+require 'graphql/client/http'
+
+module ShopifyAPI
+  module GraphQL
+    class HTTPClient < ::GraphQL::Client::HTTP
+      def initialize(api_version)
+        @api_version = api_version
+      end
+
+      def headers(_context)
+        ShopifyAPI::Base.headers
+      end
+
+      def uri
+        ShopifyAPI::Base.site.dup.tap do |uri|
+          uri.path = @api_version.construct_graphql_path
+        end
+      end
+    end
+  end
+end

lib/shopify_api/graphql/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+require 'rails/railtie'
+
+module ShopifyAPI
+  module GraphQL
+    class Railtie < Rails::Railtie
+      initializer 'shopify_api.initialize_graphql_clients' do |app|
+        ShopifyAPI::GraphQL.schema_location = app.root.join('db', ShopifyAPI::GraphQL.schema_location)
+        ShopifyAPI::GraphQL.initialize_clients
+      end
+
+      rake_tasks do
+        load 'shopify_api/graphql/task.rake'
+      end
+    end
+  end
+end