Merge pull request #1411 from Shopify/remove-api-version-constants

[Breaking] Remove API version constants

Author: lizkenyon

BREAKING_CHANGES_FOR_V15.md

@@ -1,5 +1,65 @@
 # Breaking change notice for version 15.0.0
 
+## Removal of `LATEST_SUPPORTED_ADMIN_VERSION` and `RELEASE_CANDIDATE_ADMIN_VERSION` constants
+
+The `LATEST_SUPPORTED_ADMIN_VERSION` and `RELEASE_CANDIDATE_ADMIN_VERSION` constants have been removed to prevent semantic versioning (semver) breaking changes. Previously, these constants would automatically update every quarter when new API versions were released, causing unintended breaking changes for apps.
+
+### Migration Guide
+
+**If you were using these constants directly:**
+
+```ruby
+# Before (v14 and earlier)
+api_version = ShopifyAPI::LATEST_SUPPORTED_ADMIN_VERSION
+# or
+api_version = ShopifyAPI::RELEASE_CANDIDATE_ADMIN_VERSION
+
+# After (v15+)
+api_version = "2025-07" # Explicitly specify the version you want to use
+```
+
+**In your Context.setup:**
+
+The `api_version` parameter has always been required in `Context.setup`, so most apps should not be affected. However, you must now explicitly specify which API version you want to use:
+
+```ruby
+# Before (v14 and earlier)
+ShopifyAPI::Context.setup(
+  api_key: "<api-key>",
+  api_secret_key: "<api-secret-key>",
+  host: "<https://application-host-name.com>",
+  scope: "read_orders,read_products,etc",
+  is_embedded: true,
+  api_version: ShopifyAPI::LATEST_SUPPORTED_ADMIN_VERSION, # This constant no longer exists
+  is_private: false,
+)
+
+# After (v15+)
+ShopifyAPI::Context.setup(
+  api_key: "<api-key>",
+  api_secret_key: "<api-secret-key>",
+  host: "<https://application-host-name.com>",
+  scope: "read_orders,read_products,etc",
+  is_embedded: true,
+  api_version: "2025-07", # Explicitly specify the version
+  is_private: false,
+)
+```
+
+**Finding the right API version:**
+
+You can see all supported API versions by referencing:
+```ruby
+ShopifyAPI::SUPPORTED_ADMIN_VERSIONS
+# => ["unstable", "2025-10", "2025-07", "2025-04", ...]
+```
+
+**Why this change?**
+ By requiring explicit version specification, apps can:
+- Control when they upgrade to new API versions
+- Test thoroughly before upgrading
+- Avoid unexpected breaking changes from automatic version updates
+
 ## Removal of `ShopifyAPI::Webhooks::Handler`
 
 The `ShopifyAPI::Webhooks::Handler` class has been removed in favor of `ShopifyAPI::Webhooks::WebhookHandler`. The `ShopifyAPI::Webhooks::WebhookHandler` class is now the recommended way to handle webhooks.

CHANGELOG.md

@@ -3,6 +3,8 @@
 Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 ## Unreleased
 
+- [#1411](https://github.com/Shopify/shopify-api-ruby/pull/1411) Remove `LATEST_SUPPORTED_ADMIN_VERSION` and `RELEASE_CANDIDATE_ADMIN_VERSION` constants to prevent semver violations. Developers must now explicitly specify API versions. See the [migration guide](BREAKING_CHANGES_FOR_V15.md#removal-of-latest_supported_admin_version-and-release_candidate_admin_version-constants) for details.
+
 - [#1405](https://github.com/Shopify/shopify-api-ruby/pull/1405) Fix webhook registration for topics containing dots (e.g., `customer.tags_added`, `customer.tags_removed`)
 
 ## 14.11.1

lib/shopify_api/admin_versions.rb

@@ -22,12 +22,7 @@ module AdminVersions
       "2022-04",
       "2022-01",
     ], T::Array[String])
-
-    LATEST_SUPPORTED_ADMIN_VERSION = T.let("2025-07", String)
-    RELEASE_CANDIDATE_ADMIN_VERSION = T.let("2025-10", String)
   end
 
   SUPPORTED_ADMIN_VERSIONS = ShopifyAPI::AdminVersions::SUPPORTED_ADMIN_VERSIONS
-  LATEST_SUPPORTED_ADMIN_VERSION = ShopifyAPI::AdminVersions::LATEST_SUPPORTED_ADMIN_VERSION
-  RELEASE_CANDIDATE_ADMIN_VERSION = ShopifyAPI::AdminVersions::RELEASE_CANDIDATE_ADMIN_VERSION
 end

lib/shopify_api/context.rb

@@ -7,7 +7,7 @@ class Context
 
     @api_key = T.let("", String)
     @api_secret_key = T.let("", String)
-    @api_version = T.let(LATEST_SUPPORTED_ADMIN_VERSION, String)
+    @api_version = T.let("", String)
     @api_host = T.let(nil, T.nilable(String))
     @scope = T.let(Auth::AuthScopes.new, Auth::AuthScopes)
     @is_private = T.let(false, T::Boolean)
@@ -101,8 +101,8 @@ def load_rest_resources(api_version:)
         @rest_resource_loader&.setup
         @rest_resource_loader&.unload
 
-        # No resources for the unstable version or the release candidate version
-        return if api_version == "unstable" || api_version == RELEASE_CANDIDATE_ADMIN_VERSION
+        # No resources for the unstable version
+        return if api_version == "unstable"
 
         version_folder_name = api_version.gsub("-", "_")
 
@@ -155,7 +155,7 @@ def embedded?
 
       sig { returns(T::Boolean) }
       def setup?
-        [api_key, api_secret_key, T.must(host)].none?(&:empty?)
+        [api_key, api_secret_key, api_version, T.must(host)].none?(&:empty?)
       end
 
       sig { returns(T.nilable(Auth::Session)) }

test/admin_versions_test.rb

@@ -8,13 +8,5 @@ class AdminVersionsTest < Minitest::Test
     def test_supported_admin_versions
       assert_instance_of(Array, ShopifyAPI::AdminVersions::SUPPORTED_ADMIN_VERSIONS)
     end
-
-    def test_supported_latest_supported_admin_version
-      assert_instance_of(String, ShopifyAPI::AdminVersions::LATEST_SUPPORTED_ADMIN_VERSION)
-    end
-
-    def test_supported_release_candidate_admin_version
-      assert_instance_of(String, ShopifyAPI::AdminVersions::RELEASE_CANDIDATE_ADMIN_VERSION)
-    end
   end
 end