method renames and minior refactor

README.md

@@ -42,10 +42,10 @@ The `api_version` attribute can take the string or symbol name of any known vers
 By default any string or symbol will naïvely coerce into an ApiVersion. To ensure only known and active versions can be set, call
 
 ```ruby
-ShopifyAPI::ApiVersion.coercion_mode = :predefined_only
+ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
 ShopifyAPI::ApiVersion.fetch_known_versions
 ```
-Known versions are fetched and cached from https://app.shopify.com/services/apis.json. Trying to use a version outside this set will raise an error. To switch back to naïve coercion, call `ShopifyAPI::ApiVersion.coercion_mode = :define_on_unknown` (the default mode).
+Known versions are fetched and cached from https://app.shopify.com/services/apis.json. Trying to use a version outside this set will raise an error. To switch back to naïve coercion, call `ShopifyAPI::ApiVersion.version_lookup_mode = :define_on_unknown` (the default mode).
 
 For example if you want to use the `2019-04` version you would create a session like this:
 ```ruby

lib/shopify_api/api_version.rb

@@ -9,40 +9,42 @@ class InvalidVersion < StandardError; end
     UNSTABLE_HANDLE = 'unstable'
     UNSTABLE_AS_DATE = Time.utc(3000, 1, 1)
     API_PREFIX = '/admin/api/'
-    COERSION_MODES = [:predefined_only, :define_on_unknown].freeze
+    LOOKUP_MODES = [:raise_on_unknown, :define_on_unknown].freeze
 
     class << self
       attr_reader :versions
 
-      def coercion_mode
-        @coercion_mode ||= :define_on_unknown
+      def version_lookup_mode
+        @version_lookup_mode ||= :define_on_unknown
       end
 
-      def coercion_mode=(mode)
-        raise ArgumentError, "Mode must be one of #{COERSION_MODES}" unless COERSION_MODES.include?(mode)
-        sanitize_known_versions if mode == :predefined_only
-        @coercion_mode = mode
+      def version_lookup_mode=(mode)
+        raise ArgumentError, "Mode must be one of #{LOOKUP_MODES}" unless LOOKUP_MODES.include?(mode)
+        sanitize_known_versions if mode == :raise_on_unknown
+        @version_lookup_mode = mode
       end
 
-      def coerce_to_version(version_or_handle)
+      def find_version(version_or_handle)
         return version_or_handle if version_or_handle.is_a?(ApiVersion)
         handle = version_or_handle.to_s
-
         @versions ||= {}
         @versions.fetch(handle) do
-          if @coercion_mode == :predefined_only
-            error_msg = if @versions.empty?
-              "No versions defined. You must call `ApiVersion.fetch_known_versions` first."
-            else
-              "`#{handle}` is not in the defined version set. Available versions: #{@versions.keys}"
-            end
-            raise UnknownVersion, "ApiVersion.coercion_mode is set to `:predefined_only`. #{error_msg}"
+          if @version_lookup_mode == :raise_on_unknown
+            raise UnknownVersion, unknown_version_error_message(handle)
           else
-            @versions[handle] = ApiVersion.new(handle: handle)
+            add_to_known_versions(ApiVersion.new(handle: handle))
           end
         end
       end
 
+      def coerce_to_version(version_or_handle)
+        warn(
+          '[DEPRECATED] ShopifyAPI::ApiVersion.coerce_to_version be removed in a future version. ' \
+            'Use `find_version` instead.'
+        )
+        find_version(version_or_handle)
+      end
+
       def fetch_known_versions
         @versions = Meta.admin_versions.map do |version|
           [version.handle, ApiVersion.new(version.attributes.merge(verified: version.persisted?))]
@@ -57,6 +59,10 @@ def define_known_versions
         fetch_known_versions
       end
 
+      def add_to_known_versions(version)
+        @versions[version.handle] = version
+      end
+
       def clear_known_versions
         @versions = {}
       end
@@ -86,6 +92,12 @@ def sanitize_known_versions
           [handle, @versions[handle]]
         end.compact.to_h
       end
+
+      def unknown_version_error_message(handle)
+        msg = "ApiVersion.version_lookup_mode is set to `:raise_on_unknown`. \n"
+        return msg + "No versions defined. You must call `ApiVersion.fetch_known_versions` first." if @versions.empty?
+        msg + "`#{handle}` is not in the defined version set. Available versions: #{@versions.keys}"
+      end
     end
 
     attr_reader :handle, :display_name, :supported, :latest_supported, :verified

lib/shopify_api/resources/base.rb

@@ -66,7 +66,7 @@ def api_version
       end
 
       def api_version=(version)
-        self._api_version = version.nil? ? nil : ApiVersion.coerce_to_version(version)
+        self._api_version = version.nil? ? nil : ApiVersion.find_version(version)
       end
 
       def prefix(options = {})

lib/shopify_api/session.rb

@@ -127,7 +127,7 @@ def site
     end
 
     def api_version=(version)
-      @api_version = version.nil? ? nil : ApiVersion.coerce_to_version(version)
+      @api_version = version.nil? ? nil : ApiVersion.find_version(version)
     end
 
     def valid?

test/api_version_test.rb

@@ -2,51 +2,51 @@
 require 'test_helper'
 
 class ApiVersionTest < Test::Unit::TestCase
-  test "coerce_to_version returns any version object given" do
+  test "find_version returns any version object given" do
     version = ShopifyAPI::ApiVersion.new(handle: :unstable)
-    assert_same(version, ShopifyAPI::ApiVersion.coerce_to_version(version))
+    assert_same(version, ShopifyAPI::ApiVersion.find_version(version))
   end
 
-  test "coerce_to_version converts a known version into a version object" do
+  test "find_version converts a known version into a version object" do
     versions = [
       ShopifyAPI::ApiVersion.new(handle: :unstable),
       ShopifyAPI::ApiVersion.new(handle: '2019-01'),
     ]
 
     assert_equal(versions, [
-      ShopifyAPI::ApiVersion.coerce_to_version('unstable'),
-      ShopifyAPI::ApiVersion.coerce_to_version('2019-01'),
+      ShopifyAPI::ApiVersion.find_version('unstable'),
+      ShopifyAPI::ApiVersion.find_version('2019-01'),
     ])
   end
 
-  test "coerce_to_version removes unverified versions from version set if mode is set to :predefined_only" do
-    ShopifyAPI::ApiVersion.coercion_mode = :define_on_unknown
+  test "find_version removes unverified versions from version set if mode is set to :raise_on_unknown" do
+    ShopifyAPI::ApiVersion.version_lookup_mode = :define_on_unknown
     assert ShopifyAPI::ApiVersion.versions.values.all?(&:verified?)
     assert_equal 5, ShopifyAPI::ApiVersion.versions.size
 
-    ShopifyAPI::ApiVersion.coerce_to_version('2019-30')
+    ShopifyAPI::ApiVersion.find_version('2019-30')
     refute ShopifyAPI::ApiVersion.versions.values.all?(&:verified?)
     assert_equal 6, ShopifyAPI::ApiVersion.versions.size
-    ShopifyAPI::ApiVersion.coercion_mode = :predefined_only
+    ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
 
     assert ShopifyAPI::ApiVersion.versions.values.all?(&:verified?)
     assert_equal 5, ShopifyAPI::ApiVersion.versions.size
   end
 
-  test "coerce_to_version does not raise when coercing a string if no versions are defined when coercion_mode is :define_on_unknown" do
+  test "find_version does not raise when coercing a string if no versions are defined when version_lookup_mode is :define_on_unknown" do
     ShopifyAPI::ApiVersion.clear_known_versions
-    ShopifyAPI::ApiVersion.coercion_mode = :define_on_unknown
-    assert_equal :define_on_unknown, ShopifyAPI::ApiVersion.coercion_mode
+    ShopifyAPI::ApiVersion.version_lookup_mode = :define_on_unknown
+    assert_equal :define_on_unknown, ShopifyAPI::ApiVersion.version_lookup_mode
     assert_nothing_raised do
-      ShopifyAPI::ApiVersion.coerce_to_version('made up version')
+      ShopifyAPI::ApiVersion.find_version('made up version')
     end
   end
 
-  test "coerce_to_version does raise when coercing a string if no versions are defined when coercion_mode is :predefined_only" do
+  test "find_version does raise when coercing a string if no versions are defined when version_lookup_mode is :raise_on_unknown" do
     refute ShopifyAPI::ApiVersion.versions['made up version']
-    ShopifyAPI::ApiVersion.coercion_mode = :predefined_only
+    ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
     assert_raises ShopifyAPI::ApiVersion::UnknownVersion do
-      ShopifyAPI::ApiVersion.coerce_to_version('made up version')
+      ShopifyAPI::ApiVersion.find_version('made up version')
     end
   end
 

test/detailed_log_subscriber_test.rb

@@ -37,7 +37,7 @@ def setup
   def teardown
     super
     ShopifyAPI::ApiVersion.clear_known_versions
-    ShopifyAPI::ApiVersion.coercion_mode = :predefined_only
+    ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
   end
 
   def set_logger(logger)

test/pagination_test.rb

@@ -4,7 +4,7 @@ class PaginationTest < Test::Unit::TestCase
   def setup
     super
 
-    @version = ShopifyAPI::ApiVersion.coerce_to_version('2019-10')
+    @version = ShopifyAPI::ApiVersion.find_version('2019-10')
     ShopifyAPI::Base.api_version = @version.to_s
     @next_page_info = "eyJkaXJlY3Rpb24iOiJuZXh0IiwibGFzdF9pZCI6NDQwMDg5NDIzLCJsYXN0X3ZhbHVlIjoiNDQwMDg5NDIzIn0%3D"
     @previous_page_info = "eyJsYXN0X2lkIjoxMDg4MjgzMDksImxhc3RfdmFsdWUiOiIxMDg4MjgzMDkiLCJkaXJlY3Rpb24iOiJuZXh0In0%3D"
@@ -131,7 +131,7 @@ def setup
   end
 
   test "raises on an invalid API version" do
-    version = ShopifyAPI::ApiVersion.coerce_to_version('2019-04')
+    version = ShopifyAPI::ApiVersion.find_version('2019-04')
     ShopifyAPI::Base.api_version = version.to_s
 
     fake 'orders', :method => :get, :status => 200, api_version: version, :body => load_fixture('orders')
@@ -143,7 +143,7 @@ def setup
   end
 
   test "does not raise on the unstable version" do
-    version = ShopifyAPI::ApiVersion.coerce_to_version('unstable')
+    version = ShopifyAPI::ApiVersion.find_version('unstable')
     ShopifyAPI::Base.api_version = version.to_s
     @next_link_header = "<https://this-is-my-test-shop.myshopify.com/admin/api/unstable/orders.json?page_info=#{@next_page_info}>; rel=\"next\""
 

test/session_test.rb

@@ -345,6 +345,6 @@ def generate_signature(params)
 
   def any_api_version
     version_name = ['2019-01', :unstable].sample(1).first
-    ShopifyAPI::ApiVersion.coerce_to_version(version_name)
+    ShopifyAPI::ApiVersion.find_version(version_name)
   end
 end

test/test_helper.rb

@@ -63,7 +63,7 @@ def teardown
         ShopifyAPI::Base.user = nil
 
         ShopifyAPI::ApiVersion.clear_known_versions
-        ShopifyAPI::ApiVersion.coercion_mode = :predefined_only
+        ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
       end
 
       # Custom Assertions
@@ -95,7 +95,7 @@ def fake(endpoint, options={})
         body   = options.has_key?(:body) ? options.delete(:body) : load_fixture(endpoint)
         format = options.delete(:format) || :json
         method = options.delete(:method) || :get
-        api_version = options.delete(:api_version) || ShopifyAPI::ApiVersion.coerce_to_version('2019-01')
+        api_version = options.delete(:api_version) || ShopifyAPI::ApiVersion.find_version('2019-01')
         extension = ".#{options.delete(:extension)||'json'}" unless options[:extension]==false
         status = options.delete(:status) || 200
         url = if options.has_key?(:url)