shopify_api/docs/graphql.md at main · HashNotAdam/shopify

GraphQL client

The shopify_api gem includes a full featured GraphQL client to interact with Shopify's GraphQL Admin API. GitHub's graphql-client is used as the underlying client and this library integrates it with our existing session, authentication, and API versioning features.

Example

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

Dump the schema

One of the main benefits of GraphQL is its schema and type system 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:

Private apps

$ rake shopify_api:graphql:dump SHOP_URL="https://API_KEY:PASSWORD@SHOP_NAME.myshopify.com" API_VERSION=2020-01

Public apps

$ rake shopify_api:graphql:dump SHOP_DOMAIN="SHOP_NAME.myshopify.com" ACCESS_TOKEN="SHOP_TOKEN" 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:

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 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:

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:

query = ShopifyAPI::GraphQL.client.parse <<-'GRAPHQL'
  {
    shop {
      name
    }
  }
GRAPHQL

result = ShopifyAPI::GraphQL.client.query(query)
result.data.shop.name

See the graphql-client documentation 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:

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::Clients 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. 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.

Using a custom GraphQL Client

By default ShopifyAPI::GraphQL wraps the Github GraphQL Client library. However, this client may not suitable for various reasons. If you wish to expand on the interface of the client or improve the required functions for your use case you can implement a client of your own.

To use a custom GraphQL Client:

class CustomGraphQLClient < ::GraphQL::Client
end

ShopifyAPI::GraphQL.graphql_client = CustomGraphQLClient

Using a custom query execution adapter

Github's GraphQL Client uses an adapter pattern so that you can define how you interact with GraphQL API's. Shopify provides a minimal implementation in ShopifyAPI::GraphQL::HTTPClient. If you need to add additional functionality pre, during or post query execution you can consider implementing these within a custom query execution adapter, inheriting from ShopifyAPI::GraphQL::HTTPClient which provides the necessary implementation for headers, url, and api versions

To set a custom query executiona dapter set ShopifyAPI::GraphQL.execution_adapter to your client:

class RaisingHTTPClient < ShopifyAPI::GraphQL::HTTPClient
  def execute(document:, operation_name: nil, variables: {}, context: {})
    result = super
    do_work(result)
  end

  private

  def do_work(result)
    result
  end
end

ShopifyAPI::GraphQL.execution_adapter = RaisingHTTPClient

Note, the execution adapter has client in the name. This is to remain consistent with the naming conventions within the Github GraphQL Client library.

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:

Migrate usage

Previously a client was initialized with ShopifyAPI::GraphQL.new:

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:

client = ShopifyAPI::GraphQL.client

SHOP_NAME_QUERY = client.parse <<-'GRAPHQL'
  {
    shop {
      name
    }
  }
GRAPHQL

result = client.query(SHOP_NAME_QUERY)
result.data.shop.name

See make queries for more usage details.