[Updated] A review of versioning at Shopify; what you need to know by July 1st

Highlighted
Shopify Staff
Shopify Staff
56 4 28

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.

Highlighted
New Member
2 0 0

Hello,

We don't have a partner account but we have our own private app.

In the private app, what should we set up in order to be able to see the deprecation header?

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.

0 Likes
Highlighted
Excursionist
29 0 22

Whilst this is welcome, the change to April from the original July date was not communicated clearly. We understand the documentation was updated but with no announcement about the original July date changing to April - until 5th March, that was poor. 

 

“But the plans were on display…”
“On display? I eventually had to go down to the cellar to find them.”
“That’s the display department.”
“With a flashlight.”
“Ah, well, the lights had probably gone.”
“So had the stairs.”
“But look, you found the notice, didn’t you?”
“Yes,” said Arthur, “yes I did. It was on display in the bottom of a locked filing cabinet stuck in a disused lavatory with a sign on the door saying ‘Beware of the Leopard.”

 

Glad it's now changed back to the original date. Thank you.

0 Likes
Highlighted
Shopify Staff
Shopify Staff
192 8 44

Hi Simon,

Just to be clear, the original date was April 1st. This was the date set in April of 2019 when we announced versioning.

Because of the chaos of COVID, we chose to delay the version end of life to a new date: July 1st.

0 Likes
Highlighted
Excursionist
29 0 22
Hi Shayne.

Thanks for replying. We have comms in writing from Shopify, from Autumn
2019 that show this date as Set for July 1st, not April 1st. That's all.
Thanks.
0 Likes
Highlighted
Shopify Partner
13 0 0

why my app is calling 2019-07 api version ??

event i haven't pass any version in api call 

https://*******.myshopify.com/api/graphql

 

please help me 

because its live app 

 

0 Likes
Highlighted
Shopify Partner
13 0 0
0 Likes
Highlighted
Shopify Staff
Shopify Staff
192 8 44

Hey Simon, mind PMing me a copy of those comms?
 
Dev_2ezasiaPM me with the API key that's seeing the issue and I'll take a look at your app to see what might be wrong!

Highlighted
Shopify Partner
16 0 6
Highlighted
New Member
1 0 0

I recently took over this area of development and am rather confused.

 

Is it just the call to the API using Pages that is deprecated or do I need to do something with our private app on Shopify?  How can I tell it I have it properly fixed?
I have updates our calls *to* Shopify to use the new Link methodology and the Health Meter has not changed in a few days, but that doesn't really let me know if the issue still exists or not.

Any additional clarification would be greatly appreciated!


Carla

0 Likes