Add ApiVersion coercion_modes and fetch_known_versions from Shopify

[jtgrenz]

This PR allows us to dynamically define api_versions based on the response from https://app.shopify.com/services/apis.json

This removes the need to manually updated the gem every time a new version is released or set to end of life.

When the gem is required, we define a set of known versions from the unauthenticated services/apis.json endpoint and everything behaves more or less like it did before. If an unknown version is attempted to be set (ie as of today, 2020-04 or taco-42) an UnknownVersion error is raised with all known versions as message.

If for some reason the known_version_set cannot be initialized at start, then we default to assuming the version is valid, and rely on the server to handle the request and return an error if necessary. Developers can retry defining the version set by calling ShopifyAPI::ApiVersion.define_known_versions at anytime. Any version that was fetched from the server will have persisted? return true, and any on the fly version instances would return false.

ApiVersion attributes were solidified internally at shopify I think after version support was added to the gem, so I also deprecated and aliased methods like #name and #stable? to #handle and #supported?

[tanema]

I have a couple questions but no show stoppers

[tanema]

Is there a recommended way to do this same thing after this method is removed? Is this just discouraged going forward?

[jtgrenz]

I think we wanted to discourage anyone trying to set the version to the latest version automatically since it's likely to break apps. Bumping to the latest version should hopefully be intentional.

It can still be computed however since each ApiVersion has a latest_supported attribute, its just a little more work.

ShopifyAPI::Meta.admin_versions.find(&:latest_supported?) works at the expense of another api call, but we could also cache the versions in Meta.admin_versions

[alexaitken]

latest_supported_version is used by the ShopifyApp gem https://github.com/Shopify/shopify_app/blob/0900ddcb2f268f6efe3e184739ee83eeab3a0020/lib/generators/shopify_app/install/install_generator.rb#L12 to run the generators.

It can now use ShopifyAPI::Meta.admin_versions.find(&:latest_supported?) to find that info.

[jtgrenz]

updated per @alexaitken 's comments on slack. ApiVersion now supports two coercion modes. The default will just accept whatever handle you give it and leave it to the server to deal with any invalid versions, probably what you would want in production since you should have everything tested already.

The second stricter mode will not allow you to set any version that is not pre-defined. Setting ApiVersion.coercion_mode = :predefined_only will require you to fetch the known versions from Shopify with ApiVersion.define_known_versions. Theres no more remote request when requiring the gem and any developers who want to pre-define versions on boot can do so in an initializer.

Little more flexibility for different developers for different environments.

Readme still needs to be updated and this needs a rebase

[jtgrenz]

Just pushed an update and rebased against master.

I made ShopifyAPI::ApiVersion a PORO so its more light weight like Alex suggested. This now means that ShopifyAPI::Meta.admin_versions no longer returns an array of ShopifyAPI::ApiVersions but instead falls back to using ActiveResource magic and returns an array of ShopifyAPI::Meta::Versions instead.

When using ShopifyAPI::ApiVersion.define_known_versions, we still grab the array of versions from Meta but we then build and cache new lighter weight ApiVersion objects from the fetched ShopifyAPI::Meta::Version.attributes hash. Instead of using persisted? to verify if it was fetched from Shopify or just defined at runtime, you would use verified?

[eapache]

A few minor comments, and the README needs updating, but approach LGTM.

[eapache]

I might call this fetch_known_versions to be explicit that it involves a remote lookup

[jtgrenz]

Yeah I think I had that at first and at some point changed it back to minimize the number of changes or something? 🤔 It sorta made sense at the time, but I think you're right that fetch is a better choice.

Not sure if I should just rename this or alias it and issue a depreciation warning

[eapache]

clear_known_versions?

[jtgrenz]

same concern as define/fetch_known_versions

[eapache]

We should maybe mention that this set currently-supported APIs only

[jtgrenz]

well it includes release candidate as well which is unsupported.

[jtgrenz]

Just pushed an update that cleans up a few things. I suppose this is a good time to summarize the whole change again.

New

• Adds ShopifyAPI::Meta. This Meta class inherits from ActiveResource::Base and not ShopifyAPI::Base. It returns read only information about our Apis and their versions. It fetches data from https://app.shopify.com/services/apis.json and does not use authentication.
• Adds apis.json and api_versions.json test fixtures.
• Adds MetaTestCase to test that Meta.admin_versions returns an array of admin versions.

Changed

ShopifyAPI::ApiVersion

Class methods

• replaces self. class methods with class << self style methods.
• adds .versions method to return hash of known versions in { handle: version.attributes } format.
• adds .version_lookup_mode and .version_lookup_mode= which changes how we look up versions from the know versions list. Valid options are :raise_on_unknown and :define_on_unknown
• adds .find_version which returns a version from the known versions set or instantiates a new one and adds it to the set (based on version_lookup_mode)
• adds .fetch_known_versions which looks up version info from server via ShopifyAPI::Meta and adds them to the known version set.
• adds .add_to_known_versions which adds a version to the known version set
• adds private .sanitize_known_versions which removes any version from the known set that is not verified.
• adds private .unknown_version_error_message which returns an error message for an unknown version when version_lookup_mode is :raise_on_unknown.
• Adds ApiVersion.initialize. Accepts an attributes hash argument. handle: is required, all other attributes default to false.

Instance Methods

• redefines #construct_api_path and #construct_graphql_path to use the version handle in the path.
• adds #handle_as_date method to convert a version handle into a date for comparison. If handle == :unstable, the date is set to the year 3000 so its always in the future.
• adds #unstable? which is true if handle == 'unstable'
• adds accessors for all attributes.
• adds #== equality method. Returns true if the version handles between two objects match.

Misc

• deletes ShopifyAPI::DefinedVersions
• removes ShopifyAPI::ApiVersion.define_known_versions from shopify_api.rb
• updates calls to deprecated methods to use new methods.
• updates readme.

Deprecated

ApiVersion

• .coerce_to_version deprecated. use .find_version
• .define_known_versions deprecated. Use .fetch_known_versions
• .clear_defined_versions deprecated. Use. .clear_known_versions
• .latest_stable_version deprecated. Use ShopifyAPI::Meta.admin_versions.find(&:latest_supported)
• #name deprecated. Use #handle
• #stable? deprecated. Use #supported?.

Removed

• Removed ShopifyAPI::ApiVersion::Release and ShopifyAPI::ApiVersion::Unstable. Theres nothing really special about these that require another class.

[tylerball]

This approach is great, after living with API Versioning for a while I think it's clear we should leave it up to developers to define which versions they're using.

Related to this, I'm not sure developers will use predefined_only, as its a more involved setup and extra request when they could just set and forget. I'm okay with it being available though, as it could be useful in our tooling and shopify_apps generators as discussed.

[alexaitken]

We can close #603 and go with this setup.

should this be a breaking change that requires a major version bump @nwtn @tylerball

[jtgrenz]

sweet. I'll fix these merge conflicts and 🚢

[jtgrenz]

fixed merge conflicts and rebased after merging #605. I added a new commit to add more methods to ApiVersion::NullVersion so it raises a more useful error if you try to call any of the new methods added to ApiVersion (like handle, display_name, verified?, etc).

[jtgrenz]

Forgot about this on friday. Rebased again and it should be good to merge as soon as CI is done.

@tylerball did we want to release this as version 8.0.0? Is there anything else we need to include in a major version bump?