The Shopify API versions are a crucial part of the Shopify platform, enabling developers to create robust and scalable applications for Shopify merchants. Each version provides a stable, consistent interface for a specified period, allowing developers to build and update their apps confidently.
With regular updates, Shopify ensures that its API versions incorporate the latest features and improvements, while also providing ample notice and transition time for any breaking changes. In this post, BSS Commerce Shopify will introduce you to Shopify API versions and their types, guide you through their usage and benefits, and show you how to stay updated with the latest versions.
Now let’s dive in!
Contents
Introduction to Shopify API Versions
Shopify API versions play a pivotal role in eCommerce development. They provide a consistent and reliable interface for developers to build and enhance applications for Shopify merchants. API versioning is a crucial practice in software development, aimed at preventing disruptions in service due to changes in the API. It allows developers to use different versions of an API, each offering specific functionalities and ensures that existing features remain intact while new ones are added.
Here are the benefits of the Shopify API versions that you can utilize:
- Stability: Each version offers a stable interface for a specified period, allowing developers to build and update their apps without worrying about sudden changes.
- Forward Compatibility: Regular updates mean that the API versions always have the latest features and improvements.
- Transition Time: Shopify provides ample notice before deprecating an API version, giving developers enough time to adapt to the changes.
In essence, Shopify API versions are a testament to Shopify’s commitment to providing a robust, developer-friendly platform that evolves with the needs of its users. Therefore, understanding Shopify latest API versions is key to creating effective Shopify applications.
02 Types of APIs Shopify
API versioning enables Shopify to constantly enhance the platform while providing third-party developers with a reliable roadmap for feature upgrades and deprecations. Below are the main types of APIs and how they work, which you can consult:
#1 Versioned APIs
Versioned APIs include:
- Admin API (GraphQL and REST)
- Storefront API
- Customer Account API
- Hydrogen
- Hydrogen React
- Partner API
- Payments Apps API
- Checkout UI extensions
- Admin UI extensions
- Function APIs
Why Should You Use Versioned APIs?
- Predictability: Versioned APIs provide a predictable path for upgrades and deprecations. Developers can choose to use a specific version of the API that suits their needs and can plan for changes when a new version is released.
- Stability: Once an API version is released, its features and behavior remain stable. This allows developers to build and maintain applications without worrying about sudden changes in the API’s behavior.
- Forward Compatibility: Versioned APIs allow developers to use new features without disrupting the functionality of their current applications. They can opt to use a newer version of the API to access these features when they’re ready.
#2 Unversioned APIs
Unversioned APIs include:
- Ajax API
- Liquid
- OAuth endpoints (including AccessScope)
- Any other resources not explicitly listed as versioned
Why Should You Use Unversioned APIs?
- Simplicity: Unversioned APIs are simpler to use because there’s only one version to work with. Developers don’t have to worry about which version they should use.
- Agility: Changes and improvements can be made quickly in unversioned APIs, as there’s no need to maintain backward compatibility with older versions.
- Risk of Breaking Changes: Unversioned APIs can introduce breaking changes that might disrupt the functionality of existing applications. Developers need to be vigilant about updates to the API to ensure their applications continue to function correctly.
Overall, versioned APIs offer predictability and stability, making them suitable for large, complex projects. On the other hand, unversioned APIs offer simplicity and agility, which might be preferable for smaller, more flexible projects. Therefore, the choice between versioned and unversioned APIs depends on the specific needs and constraints of your project.
Release Schedule of Latest Shopify API Versions
Shopify introduces a new API version every quarter, specifically every 3 months. The version titles are structured based on dates to ensure clarity and significance, such as 2023-01. Here is a sample outline of the release dates for the year 2023:
Stable versions are released at 5 pm UTC.
Each stable version is supported for a minimum of 12 months, with at least 9 months of overlap between two consecutive stable versions. This gives developers 9 months to test and migrate their apps to the new version before support for the previous version is removed. When a new version reaches beyond the API, a developer preview is made available. It’s strongly recommended to update apps to the latest stable API version every quarter. If an app uses an unsupported version, Shopify defaults to the oldest supported version.
For instance, when Shopify removes 2023-07, API requests to this version will be served with 2023-10. If a request doesn’t include a version, the API defaults to the oldest supported version. However, relying on this default behavior for adopting deprecated changes is not recommended. As apps are updated, they should specify the API version with every request, making them version-aware and anchoring the code to a specific set of features.
Example version support schedule:
Shopify API Versions: How to Make Requests to
The Shopify API versions are specified within the URLs used by your app to make requests:
- REST Admin API URL: /admin/api/{api_version}/{endpoint}.json
- GraphQL Admin API URL: /admin/api/{api_version}/graphql.json
- Storefront API URL: /api/{api_version}/graphql.json
- Payments Apps API URL: /payments_apps/api/{api_version}/graphql.json
For instance, the subsequent URLs send requests to version 2024-01:
- Rest Admin API URL: /admin/api/2024-01/products.json
- GraphQL Admin API URL: /admin/api/2024-01/graphql.json
- Storefront API URL: /api/2024-01/graphql.json
- Payments Apps API URL: /payments_apps/api/2024-01/graphql.json
There are multiple supported versions of the APIs accessible, and you can indicate the desired version by substituting the version name in the URL. The API responses from Shopify include the header X-Shopify-API-Version, which provides the API version utilized for executing the request. When you ensure that your app is up to date, it will align with the API version specified in your request. If the returned version differs, it indicates that your app is outdated and is utilizing the default API version.
TAKE NOTE: If you are developing your app in Ruby, Python, or Node and utilizing the Admin API, you have the convenience of using the official libraries to interact with the Admin API and effortlessly set the API version.
Moreover, if you are utilizing any of the Storefront Software Development Kits (SDK), it is important to note that each newly released SDK automatically sets the API version for you. To determine the supported API version for each SDK version, refer to the release notes specific to that SDK version.
Shopify API Release Candidates & Unstable API Versions: What Are They?
Release candidates
Release candidates provide a preview of the upcoming changes set for the next stable version, allowing you to initiate the app update process promptly. API release candidates are synchronized with the stable version releases. For instance, if version 2023-01 is launched on January 1, 2023, the release candidate for version 2023-04 will be accessible simultaneously.
The release candidate may include both backward-compatible and backward-incompatible modifications, enabling you to anticipate these adjustments before the stable release. Therefore, it is advised not to utilize release candidates in a production environment.
Unstable Shopify API versions
Unstable API versions are constantly being updated with new features and changes that are still being developed. These versions may undergo both backwards-incompatible and backwards-compatible modifications on a regular basis. While changes typically debut in the unstable version before a stable release, there is no assurance that alterations made in the unstable version will be included in the final release. It is possible for a feature to be introduced in an unstable version only to be eliminated later on.
It is recommended to utilize unstable API versions for testing purposes only and avoid using them in a production environment.
For instance, you have the option to utilize the subsequent API URLs for sending requests to the unreliable API:
- REST Admin API request: https://{shop}.myshopify.com/admin/api/unstable/products.json
- GraphQL Admin API request: https://{shop}.myshopify.com/admin/api/unstable/graphql.json
- Storefront API request: https://{shop}.myshopify.com/api/unstable/graphql.json
- Payments Apps API request: https://{shop}.myshopify.com/payments_apps/api/unstable/graphql.json
Deprecation Practices for Shopify API Versions
The Shopify API may deprecate certain parts if they are deemed unnecessary, unsafe, or outdated. Once deprecated, these parts are removed in newer versions of the API. The deprecation is then applied retrospectively to previous stable versions of the API. Whenever a deprecation is introduced, the developer changelog will provide additional details and relevant migration information.
Since each version of the API is supported for at least a year, there is always a minimum of 9 months overlap between versions. This gives you ample time to update your app and ensure it supports the deprecations.
#1. Removing parts of a Shopify API
Deprecated fields or types in GraphQL and deprecated properties or resources in REST will be eliminated in a future release. For instance, a deprecated field in 2023-07 could be removed in 2023-10.
#2. Apps using deprecated resources
If a public application or sales channel persists in utilizing unsupported resources beyond the upgrade deadline, it will be removed from the Shopify App Store. Furthermore, individuals who install an unsupported public application, unsupported custom application, or unsupported sales channel will encounter a warning message while going through the installation procedure.
If your application persists in utilizing API resources that are not supported, users will face a minimum 7-day installation block for the app.
Within the Shopify admin interface, users will encounter cautionary notifications alerting them that the app they are using is not supported. These notifications will be displayed to users exclusively in cases where the app accesses unsupported resources post the upgrade deadline. The warnings will automatically disappear 7 days following the detection of the last instance of accessing unsupported resources. It is important to note that neither you nor the user can manually delete these warnings.
CAUTION: If you utilize the Shopify API in an independent application that necessitates regular updates, such as a desktop or mobile app, it is crucial for your users to update their app before the upgrade deadline to ensure its uninterrupted functionality. Consequently, you may need to update your app well in advance of the migration deadline, allowing your users ample time to update their respective apps. Failure to comply with this requirement may lead to your app being delisted or users being cautioned or prevented from installing your app if any unsupported resources are called upon.
Conclusion
In general, Shopify API versions provide a reliable and predictable way for developers to build and maintain their apps. Each stable version is supported for at least 12 months, with a 9-month overlap between two consecutive versions, allowing ample time for testing and migration.
In addition, Shopify also provides developer previews for changes beyond the API; thereby, it’s recommended to update apps to the latest stable API version quarterly. If an app uses an unsupported version, Shopify defaults to the oldest supported version. However, developers are advised not to rely on this default behavior for adopting deprecated changes but to specify the API version with every request, making their apps version-aware and anchoring the code to a specific set of features.
Hope that the sharing in this post provided by the BSS Commerce Shopify about Shopify API versions is helpful for you. Don’t forget to visit our site to explore the latest news and knowledge about the eCommerce and Shopify industries.
Check out Up-to-Date Conversion-Boosting Shopify Apps by BSS Commerce to Leverage Your Store!
