BREAKING_CHANGES_FOR_V10.md
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.
Here are the main features version 10 provides:
ActiveResource (though not identical), that provide methods for all endpoints defined in our REST API reference, as well as direct definition of known attributes.Please refer to the Getting Started guide in this repository for instructions on how to use each of these components.
Browsers stopped allowing 3rd party cookies, even after jumping through several ITP hoops, which made the code even more more complex and error prone.
authenticatedFetch were introduced to make it possible for apps to authenticate requests without depending on cookies.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.
Most feedback we got previously was due to the ActiveResource classes failing out of sync with the API because:
To solve the REST problems:
With this, a lot changed in how apps access the library. Here are the updates you should make when migrating to v10:
ShopifyAPI::Base class has been removed. Previous versions of this gem used this class to configure API request setting like:
ShopifyAPI::Base.api_version = "xxxx"api_version in ShopifyAPI::Context.setupUser-Agent on API request header
ShopifyAPI::Base.header["User-Agent"] = "xxxxx"user_agent_prefix in ShopifyAPI::Context.setupShopifyAPI::Base.header["User-Agent"] = "xxxxx"ShopifyAPI::Clients::HttpRequestInitializing 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.
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)
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.
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.
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"]
ActiveResource has been deprecated, REST API requests must now be refactored to use the new format that better represents our REST API schema.ShopifyAPI::Base.api_version, that has been deprecated. It's now configured in ShopifyAPI::Context.setup.⚠️ 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>) |
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.
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)
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.
ShopifyAPI:
ShopifyApp Gem (Rails):
Shopify API: