Before versioning, apps could only interact with the latest and greatest form of our APIs. As Shopify released features to merchants, the APIs tied to these features also evolved, and apps had to be ready to adapt to the new way of doing things very quickly.
We recognized that this developer experience was not ideal. It wasn’t obvious how partners could know if things would break on any given day, and these changes would totally overtake app development roadmaps. In order to solve this, Shopify introduced API versioning to provide stability and a scheduled cadence to our releases.
As we near the 1 year mark of shipping versioning, let’s review how it all works, and what you need to look out for in 2020.
Versioning Recap
To get started, let’s recap the fundamentals of API versioning at Shopify.
1. Shopify releases a version every quarter.
Typically, these releases happen on or around January 1st, April 1st, July 1st, and October 1st. Versions are named in a year-month format, ensuring that it will always be easy to identify the time the version became stable, as well as compare the timelines of multiple versions.
2. Apps make requests to a specific version of the API by specifying it in the request URL.
While the Shopify APIs continuously evolve, apps can choose a stable version to build on to ensure that the API contract remains constant. Keep in mind that this means that any features released after your targeted version won’t be accessible until you update your request URL.
3. Shopify releases features to merchants continuously.
To ship features without affecting the latest stable APIs, Shopify uses the concept of the release candidate. The release candidate is simply the next API version, and can be targeted for requests using the same year-month format. In it, you’ll find the latest set of features that have just been released. Since the release candidate is continuously evolving, you should avoid using it for your app’s general everyday consumption of the API.
4. Apps that do not request a specific version are served the oldest supported version.
This property allowed existing apps to continue functioning when we shipped versioning, without having to provide the new URLs. This concept also applies to apps explicitly calling versions that are no longer supported.
5. Versions are supported for 1 year.
Removing support for versions enables Shopify to stay agile and make the changes needed to best serve our merchants for the long term. One year provides enough notice for apps to adopt these new changes and take advantage of new features before the old behavior is no longer available.
Add it all up
NOTE : With the evolving concerns around COVID-19 and how it is impacting communities around the world, we know that partners and merchants are making adjustments to continue running their businesses smoothly. That’s why we’ve decided to postpone the April 1 version removal to July 1, 2020.
On April 1st 2020, the following changes will come into effect on our APIs:
- The 2020-04 version will become stable and ready for general usage.
Then on July 1st 2020, the following things will happen :
- The 2019-04 and 2019-07 versions will become unsupported.
- Requests with no API version specified will be served the 2019-10 API version.
- Requests for the 2019-04 or 2019-07 versions will no longer serve those versions. Instead, these requests will fall forward to 2019-10.
- Webhooks set to 2019-04 or 2019-07 will fall forward in the same manner.
Most importantly: the 2019-07 and 2019-10 API versions include breaking API changes. If your app is making requests that would break in 2019-10, you need to take action and migrate those requests before July 1st 2020. Failure to do so will result in failed requests and a broken app.
Let’s dive into each of the breaking changes between 2019-04 and 2019-10.
Breaking Changes TL;DR
Pagination
What is it?
Page-based pagination has been removed, and has been replaced with cursor-based pagination.
What do I need to do?
Our engineering team wrote a great partner blog post that explains the ins and outs of this change, and how to migrate your calls. You can also read more about the reasoning on our engineering blog.
TL;DR Stop using the page parameter. Use page_info instead.
Featured field removed from Collects
What is it?
The featured field was removed from the collects endpoint.
What do I need to do?
Even if you aren’t using this specific field, REST returns everything by default. Because of this, you’ll receive notifications about this deprecation when using the collect endpoint.
TL;DR Update your request URL to an API version that is later than `2019-04`.
GraphQL Admin ID added to webhooks
What is it?
We added the graphql_admin_id to webhook payloads, to make it easier to make graphql calls in response, and to be more consistent with our REST payloads. This caused issues in older versions of Rails apps. Even if you aren’t using rails, it’s good practice to periodically keep your webhook API version up-to-date to ensure your payloads don’t change when your current version becomes unsupported.
TL;DR Update your webhook API version to an API version that is later than `2019-04`.
Delivery Profiles
What is it?
The activatedCarrierServices field isn't compatible with multiple origin shipping, and has been removed.
What do I need to do?
Use the availableCarrierServices field instead. It includes both the carrier service and applicable countries.
Inventory
What is it?
Deprecation for legacy inventory behavior is now extended to all apps. This behaviour has been deprecated since 2018.
What do I need to do?
Adopt the new inventory behaviour, which includes support for multiple inventory locations. To learn more, refer to migrating to support multiple locations.
How do I stay on top of changes?
Knowing the changes is a good start, but in many cases, it can be difficult to identify individual breaking requests within your whole app. To help narrow these down, we’ve introduced the following tools that automatically generate data based on your API usage.
API Health
Your partner dashboard contains a per-app API Health report, which showcases the exact changes that will affect you. In it, you’ll find the specific endpoints, links to migration guides, and last detected timestamps of deprecated requests.
Deprecation Headers
Within your app, you should also monitor incoming changes by logging the presence of the `X-Shopify-API-Deprecated-Reason` header. This header is added to requests that are deprecated and that will be unsupported within 9 months. You should update your request as per the link returned in the header.
Email
Every app has an associated emergency developer email, which Shopify uses to notify you about pending deprecations. In these emails, you’ll find information that is very similar to the API Health report. Since private apps aren’t associated with a partner dashboard, this is the main way these types of apps have to be notified about changes that will affect them.
Alex | Shopify
- Was my reply helpful? Click Like to let me know!
- Was your question answered? Mark it as an Accepted Solution
- To learn more visit the Shopify Help Center or the Shopify Blog
Shopify Discussion
Partners and Developers
