Introducing API Versioning at Shopify

Whether you are a developer building publicly available apps for the Shopify App Store, or creating custom integrations through private apps, we understand that your business is affected whenever Shopify makes updates to the platform. That’s why we default to building features in a backwards-compatible way.

Over the last 18 months, we’ve released powerful features on the platform, such as Shopify Locations and selling in multiple currencies. Building these features required us to change the way core resources are architected.

In the past, these types of projects required us to make difficult decisions: either break the API, or keep existing endpoints the same but potentially make the API more confusing over the long term. We realized that we needed a more reliable way to release valuable but complex projects that would be less disruptive for our developer and partner ecosystem to adopt.

"To ensure that future changes to the platform are predictable, clearly communicated, and easy to adopt, we’re introducing API versioning at Shopify."

To ensure that future changes to the platform are predictable, clearly communicated, and easy to adopt, we’re introducing API versioning at Shopify. Today, we’re excited to announce that we have released our first version of Shopify’s Admin API (GraphQL and REST), called 2019-04. We encourage you to start calling 2019-04 in your private and public apps today.

With API versioning, our goal is to ensure that developers feel confident building on Shopify. To achieve this, we are also introducing changes to the Partner Dashboard, the Developer Changelog, and our developer documentation to make it easier for developers to stay on top of upcoming versions.

We understand that many developers have mixed feelings about the platforms they build with adopting API versioning. We also understand that there are many different ways for platforms to approach API versioning. In this article, we’ll explain how API versioning will work at Shopify, our new developer preview environment, and where you can stay up-to-date on every version.

How API versioning will work at Shopify

As a developer building on Shopify’s APIs, it’s important to understand how API versioning will work and the impact it will have on your business.

• Release schedule: Versions are released on a quarterly cycle, on the first of January, April, July, and October.
  
  
• Naming: Versions are named after calendar dates, such as 2019-04 for the April 2019 release, 2019-07 for the July 2019 release, and so forth.
  
  
• URI structure: Versions are specified in the URI and returned in the custom response header X-Shopify-API-Version.
  Example: /admin/api/2019-04/products.json.
• Webhooks: Webhook versions are specified through the Partner Dashboard for public apps and through the admin for private apps. 
  
  
• Stable versions: Every stable version is locked for a minimum of one year, meaning that once 2019-04 has been released, it will only be changed in the event of a critical security fix until 2020-04 is released (on April 1, 2020). After this, support for 2019-04 will no longer be guaranteed. You may continue to call 2019-04 endpoints after support has ended, but it may contain breaking changes. We advise partners to keep their apps on a supported stable API.

• REST and GraphQL: Both the REST and GraphQL Admin APIs are versioned:
• REST: /admin/api/2019-04/{endpoint}.json
• GraphQL: /admin/api/2019-04/graphql.json
• Unstable API: At any given time, Shopify Partners also have access to our unstable API. As the name implies, there are no guarantees that this API will not change, so we advise developers to not use the unstable version in production. In addition, a change in the unstable API might be removed without ever being added to a stable version.
• REST: /admin/api/unstable/products.json
• GraphQL: /admin/api/unstable/graphql.json

• Release candidates: We have release candidates available to take an early look at the next version of the APIs. While we don’t recommend using release candidates in production, they can help provide a better understanding of what will be included in the next version, and help developers get a headstart with new platform features. Anything included in a release candidate will be included in the next version, but until a candidate is released as stable, there may be breaking and non-breaking changes added to it.
  
  
• APIs that will not be versioned as part of this release: We are currently only versioning our Admin API, which means the following APIs will not be versioned:
• Checkout API
• Storefront API
• Liquid (including Checkout.liquid)
• Shopify Scripts
• Ajax API
• Analytics API

• Adopting versioning: Because this is the first version, 2019-04 has the same behavior as the API called with no version. You can continue to call the Admin API with no version, and Shopify will return with the oldest supported version. However, we strongly recommend that you start calling 2019-04 in order to make your application version-aware and anchor your code to a specific set of features that are guaranteed to behave in the same way for the next 12 months.

Developer previews

Without knowing how features will work in the context of the Shopify Admin, exposing changes to the API alone often isn’t useful to developers. In order to make it easier to update your apps, we’re introducing the ability for developers to preview the user interface of upcoming features in the Partner Dashboard.

These previews will be available through a new developer preview store, allowing developers to play with upcoming features in order to better understand how they will impact merchants. Every API version that is related to a new feature in Shopify’s user interface will include a preview.

Note: Some versions will not have an associated preview if there are no new features with user interfaces included in that release.

Armed with this tool, developers can prepare for future releases by testing their apps and custom integrations, building new features, or updating marketing and support documentation.

Learn more about developer previews.

Stay up to date with versions

To ensure it’s easy to discern what has changed from one version to another, we have also revamped how we communicate and document changes to the Admin API. In particular, we’ve updated the following resources:

• Developer Changelog: The Developer Changelog will be updated so that versions are represented and changes are tracked and highlighted. Be sure to subscribe to the changelog feed to get regular updates and stay on top of new changes.
  
  
• Migration guides: Our migration guides are now all stored in one place, as a go-to resource for information on moving from one version to the next when your app is impacted by a change.
  
  
• HTTP response headers: If an endpoint is deprecated in a current or future version, Shopify will return a header in the response with information on what version the endpoint has been deprecated in, and when that change will go into effect.
  For example: X-Shopify-API-Deprecated-Reason: https://help.shopify.com/en/api/guides/inventory-migration-guide

API versioning for a healthy ecosystem

Although we’ve launched tools to help you keep up with Shopify’s changes, we want to reiterate that we default to keeping breaking changes to a minimum. We know that when we remove an endpoint or change a key for a field, we are putting days or weeks of work on our partners and merchants.

However, some changes are unavoidable. As the Shopify platform evolves to keep up with our growth, we want to make sure you’re prepared to address those changes. API versioning is one way to make that process smoother.

Questions about API versioning? Visit our developer documentation, check out the forums, or let us know in the comments below.