Skip to content

Latest commit

 

History

History
231 lines (184 loc) · 13.1 KB

BREAKING_CHANGES_FOR_V10.md

File metadata and controls

231 lines (184 loc) · 13.1 KB
Raw

Breaking change notice for version 10.0.0

We've rewritten this library for v10, so that it provides all essential features for a Shopify app without depending on the Active Resource or graphql-client libraries.

Table of Contents

New Features

Here are the main features version 10 provides:

  • OAuth support, both with online and offline tokens.
  • Full, transparent support for JWT sessions for embedded apps and cookies for non-embedded ones.
    • Removal of support for 3rd party cookies which are increasingly more difficult to use with modern browsers.
  • Admin API support
    • Auto-generated, version-specific REST resources which are similar to ActiveResource (though not identical), that provide methods for all endpoints defined in our REST API reference, as well as direct definition of known attributes.
    • A GraphQL client that doesn't rely on the ActiveResource implementation for REST.
  • Webhook management, with features for adding handlers and registering them with Shopify.
  • Storefront GraphQL API support

Please refer to the Getting Started guide in this repository for instructions on how to use each of these components.

Reasoning

  • Browsers stopped allowing 3rd party cookies, even after jumping through several ITP hoops, which made the code even more more complex and error prone.

    • Session tokens and authenticatedFetch were introduced to make it possible for apps to authenticate requests without depending on cookies.
    • The gem was too closely tied to rails on how it sets up sessions (which worked for cookies), so we had to detach the library from rails in order to be able to work with both cookies and session tokens.

  • We previously relied on an omniauth-oauth2 strategy that worked fine when cookies were the only option. But it became increasingly awkward when we moved towards session tokens, which meant re-writing the OAuth process in the gem as a whole.

    • Introducing a DB stored session persistence rather than cookie stored.

  • Most feedback we got previously was due to the ActiveResource classes failing out of sync with the API because:

    1. We have some endpoints that didn't 100% follow REST convention;
    2. We had a single class for each resource and manually maintained custom methods that didn't work across API versions.

  • To solve the REST problems:

    • We were adding support for auto-generated, version-specific resources for other languages, we decided to add them for Ruby too. But those same instances where the API doesn't follow convention would become problematic. Thus we opted for the most explicit option where every method was "custom" rather than just some, so that the resources were always consistent.

Upgrade Guide

With this, a lot changed in how apps access the library. Here are the updates you should make when migrating to v10:

1. Configuration Changes

Removed ShopifyAPI::Base

ShopifyAPI::Base class has been removed. Previous versions of this gem used this class to configure API request setting like:

  • API request version
  • Set User-Agent on API request header
    • Previously: Set by ShopifyAPI::Base.header["User-Agent"] = "xxxxx"
    • Change: Configured user_agent_prefix in ShopifyAPI::Context.setup
  • Set custom headers on API requests
    • Previously: Set by ShopifyAPI::Base.header["User-Agent"] = "xxxxx"
    • Change: Custom headers can be added to requests when you use ShopifyAPI::Clients::HttpRequest

ShopifyAPI::Context.setup

Initializing the ShopifyAPI::Context with the parameters of your app by calling ShopifyAPI::Context.setup (example below) when your app starts (e.g application.rb in a Rails app). This class holds global configurations for your app and defines how the library behaves.

ShopifyAPI::Context.setup(
  api_key: "<api-key>",
  api_secret_key: "<api-secret-key>",
  host_name: "<application-host-name>",
  scope: "read_orders,read_products,etc",
  is_embedded: true, # Set to true if you are building an embedded app
  is_private: false, # Set to true if you are building a private app
  api_version: "2021-01" # The version of the API you would like to use
  user_agent_prefix: "<user_agent_prefix>" # Set a custom prefix for "User-Agent" header when making API requests
  ###
)

See other fields accepted during ShopifyAPI::Context setup in context.rb.

2. Session Changes

ShopifyAPI::Base class has been removed, you can no longer activate session using ShopifyAPI::Base.activate_session. Instead, you can use ShopifyAPI::Context.activate_session to set the active session (ShopifyAPI::Auth::Session). If you're using the ShopifyApp gem in a Rails app, you don't have to manually set the active session if you use the included ActiveSupport concerns. See Session Docs from ShopifyApp gem.

You can also manually specify the session to use without setting the active session by passing in the session object (ShopifyAPI::Auth::Session) when instantiating new ShopifyAPI::Clients objects. If session is nil, it'll default to use active session from ShopifyAPI::Context.active_session.

# Manually specifying a session (ShopifyAPI::Auth::Session) in API clients.

# GraphQL Client
graphql_client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)

# REST Client
rest_client = ShopifyAPI::Clients::Rest::Admin.new(session: session)

# Using REST Resources
rest_resource = ShopifyAPI::Shop.new(session: session)
ShopifyAPI::Auth::Session

If you're building a Rails app, it is highly recommended for you to use the ShopifyApp gem to perform OAuth and session storage.

If you're not using Rails, please see the Performing OAuth guide on how to perform OAuth to retrieve and store sessions.

3. API Client Changes

GraphQL

  • We deprecated the dependency of graphql-client gem. You must refactor your existing query and response parsing to use our new GraphQL HTTP Client classes.
  • There is no need to dump the schema to a local JSON file before using it anymore.
  • The api version used to be set on ShopifyAPI::Base.api_version, however that's now deprecated. You may specify a specific version when initializing your client, or it'll infer to ShopifyAPI::Context.api_version as default.

⚠️ See other Admin API usage in "Make a GraphQL API call" documentation.

⚠️ See Storefront API client usage in "Make a Storefront API call" documentation.

Example refactor

ShopifyAPI Client v9

ShopifyAPI::Base.api_version = "2023-04"
client = ShopifyAPI::GraphQL.client

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

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

ShopifyAPI Client v10+

client = ShopifyAPI::Clients::Graphql::Admin.new(session: session, api_version: "2023-04")
# session must be an instance of ShopifyAPI::Auth::Session, see Section - [2. Session Changes]

SHOP_NAME_QUERY =<<~QUERY
  {
    shop {
      name
    }
  }
QUERY

response = client.query(query: query)
shop_name = response.body["data"]["shop"]["name"]

REST

Using REST Resources
  • The use of ActiveResource has been deprecated, REST API requests must now be refactored to use the new format that better represents our REST API schema.
  • Previously the api_version is specified in ShopifyAPI::Base.api_version, that has been deprecated. It's now configured in ShopifyAPI::Context.setup.
Example refactor

⚠️ You can find detailed examples on how each of the resource endpoints work in our REST reference documentation.

Please see below a (non-exhaustive) list of common replacements to guide you in your updates, using the Order resource as an example. For more detail, see order reference documentation's ruby example.

Usage Before After
Find partially paid orders Order.find(:all, params: {financial_status: "partially_paid"}) Order.all(financial_status: "partially_paid")
Find order by ID <id> Order.find(<id>) Order.find(id: <id>)
Update an order's fulfillment status order = Order.find<id>
order.fulfillment_status = "fulfilled"
order.note = "Fulfilled on September 6, 2023"
order.save		 order = Order.find(id: <id>)
order.fulfillment_status = "fulfilled"
order.note = "Fulfilled on September 6, 2023"
order.save!
Close an order order = Order.new(<id>)
order.post(:close)		 order = Order.find(id: <id>)
order.close
Delete an order order = Order.new(<id>)
order.delete		 Order.delete(id: <id>)
Note on resource connections

Previously we added helper methods to load related resource connections like orders.transactions. After the upgrade, only connected properties listed in the REST API will be supported.

For example:

  • order.transactions is not supported because transactions is not a property of the Order resource.
  • order.customer is supported because customer is a property of the Order resource.

See the full list of Order properties here.

Using REST Admin Client

If you do not want to use the REST resource classes, you can use our REST Admin client directly to make HTTP requests.

⚠️ See other REST client usage in "Make a REST API call" documentation.

Example:

# Create a new client.
client = ShopifyAPI::Clients::Rest::Admin.new(session: session)

# Update title for product with ID <id>
body = {
  product: {
    title: "My cool product"
  }
}

# Use `client.put` to send your request to the specified Shopify Admin REST API endpoint.
client.put(path: "products/<id>.json", body: body)

Generic HTTP Client

We added a new generic HttpClient wrapper to make requests and handle Shopify specific errors. All of the REST and GraphQL Clients use this HTTP Client in its foundation. You can use this to make direct HTTP API calls easily. See how the GraphQL Client makes a request with this HttpClient class in its implementation here.

Useful references

ShopifyAPI:

ShopifyApp Gem (Rails):

Shopify API: