Add context for when to override api_version

- add debug logging when the override is a NOOP
- improve documentation instructions

Co-authored-by: Kevin O'Sullivan <[email protected]>

docs/usage/graphql.md

@@ -88,7 +88,7 @@ response = client.query(query: query, variables: variables)
 # do something with the reponse
 ```
 
-To experiment with prerelease features, pass the api_version unstable when initializing the client.
+By default, the client uses the API version configured in `ShopifyAPI`.  To use a different API version, set the optional `api_version` parameter.  To experiment with prerelease API features, use `"unstable"` for the API version.
 
 ```ruby
 client = ShopifyAPI::Clients::Graphql::Admin.new(session: session, api_version: "unstable")

docs/usage/graphql_storefront.md

@@ -39,7 +39,7 @@ response = client.query(query: query)
 # do something with the returned data
 ```
 
-To experiment with prerelease features, pass the api_version unstable when initializing the client.
+By default, the client uses the API version configured in `ShopifyAPI`.  To use a different API version, set the optional `api_version` parameter.  To experiment with prerelease API features, use `"unstable"` for the API version.
 
 ```ruby
 client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url, storefront_access_token, api_version: "unstable")

lib/shopify_api/clients/graphql/client.rb

@@ -11,6 +11,15 @@ class Client
         def initialize(session:, base_path:, api_version: nil)
           @http_client = T.let(HttpClient.new(session: session, base_path: base_path), HttpClient)
           @api_version = T.let(api_version || Context.api_version, String)
+          if api_version
+            if api_version == Context.api_version
+              Context.logger.debug("Graphql client has a redundant API version override "\
+                "to the default #{Context.api_version}")
+            else
+              Context.logger.debug("Graphql client overriding default API version "\
+                "#{Context.api_version} with #{api_version}")
+            end
+          end
         end
 
         sig do

lib/shopify_api/clients/rest/admin.rb

@@ -10,6 +10,16 @@ class Admin < HttpClient
         sig { params(session: T.nilable(Auth::Session), api_version: T.nilable(String)).void }
         def initialize(session: nil, api_version: nil)
           @api_version = T.let(api_version || Context.api_version, String)
+          if api_version
+            if api_version == Context.api_version
+              Context.logger.debug("Rest client has a redundant API version override "\
+                "to the default #{Context.api_version}")
+            else
+              Context.logger.debug("Rest client overriding default API version "\
+                "#{Context.api_version} with #{api_version}")
+            end
+          end
+
           super(session: session, base_path: "/admin/api/#{@api_version}")
         end