How Shopify Manages API Versioning and Breaking Changes
engineering.shopify.com
How Shopify Manages API Versioning and Breaking Changes
1–10 of 95 posts
Re: How Shopify Manages API Versioning and Breaking Changes
#2Hi everyone. As the founder of an API company, this article has me wondering about the semantics of versioning — so I thought I’d ask the community a question. I hope the Shopify API team doesn’t mind!
When you all think about API versioning, what makes the most sense to you — a semver approach (major.minor.patch) a la NPM, or a date-based approach (2020-01-07) a la AWS? Or is some combination of the two desirable?
At Standard Library [0] we both allow people to publish APIs but also publish API proxies on behalf of partners (Stripe, Slack + others) using a semver approach. It’s not perfect but theoretically enforceable (schema parameter additions can be forced to require a minor update, schema parameter removals can be forced to require a major update). We’ve just stuck to this semver approach based on intuition and haven’t had negative feedback about it, but I do like the idea of time-based versioning.
Would love thoughts! If you want to play around you can build your own APIs using https://code.stdlib.com/, which uses the FunctionScript specification [1] to enforce HTTP request schemas.
Re: How Shopify Manages API Versioning and Breaking Changes
#3It's interesting to compare and contrast this method of API management with Stripe.
As far as I understand, the Stripe api would continue to work indefinitely so long as you lock your api version, whereas Shopify would eventually break the app as they essentially backport breaking changes to older api versions.
Initially, I thought Stripe's method was superior, and would provide the best API experience, but realized that Stripe and Shopify have different incentives w/r/t their api.
For Stripe, breaking a functioning site harms revenue, and generally the developer is the Stripe customer.
For Shopify, their customer is the store owner, and for the most part, the store will continue to function because that is mostly controlled by shopify. The developer api is for added functionality, and it is in the interest of Shopify and the merchant that those apps continue to be updated and utilizing the latest features.
So, two different ways of managing breaking changes, but both are ultimately centered around providing the best customer experience.
Re: How Shopify Manages API Versioning and Breaking Changes
#4Hi everyone. As the founder of an API company, this article has me wondering about the semantics of versioning — so I thought I’d ask the community a question. I hope the Shopify API team doesn’t mind! When you all think about API versioning, what makes the most sense to you — a semver approach (major.minor.patch) a la NPM, or a date-based approach (2020-01-07) a la AWS? Or is some combination of the two desirable? A…
I do not know any advantage of date-based versioning, other than someone knowing how new it is.
Semver is important for knowing whether or not to evaluate for breakages. You can theoretically combine both of these by making the date the patch version or supplying it as a version metadata
Re: How Shopify Manages API Versioning and Breaking Changes
#5Hi everyone. As the founder of an API company, this article has me wondering about the semantics of versioning — so I thought I’d ask the community a question. I hope the Shopify API team doesn’t mind! When you all think about API versioning, what makes the most sense to you — a semver approach (major.minor.patch) a la NPM, or a date-based approach (2020-01-07) a la AWS? Or is some combination of the two desirable? A…
Both don't say much without good changelog.
But with semver you can say: ok, I want every new version up to a new minor version (all fixes). While with a date based version you don't know how 'breaking' the changes will be.
Re: How Shopify Manages API Versioning and Breaking Changes
#6Hi everyone. As the founder of an API company, this article has me wondering about the semantics of versioning — so I thought I’d ask the community a question. I hope the Shopify API team doesn’t mind! When you all think about API versioning, what makes the most sense to you — a semver approach (major.minor.patch) a la NPM, or a date-based approach (2020-01-07) a la AWS? Or is some combination of the two desirable? A…
Both don't say much without good changelog. But with semver you can say: ok, I want every new version up to a new minor version (all fixes). While with a date based version you don't know how 'breaking' the changes will be.
How often do you feel like you find / consume changelogs when you’re looking at APIs? I feel like they’re either non-existent or non-obvious for most SaaS companies.
Do you feel like you’d trust a company’s API more if you could peruse the API changelog more easily?
Re: How Shopify Manages API Versioning and Breaking Changes
#7Hi everyone. As the founder of an API company, this article has me wondering about the semantics of versioning — so I thought I’d ask the community a question. I hope the Shopify API team doesn’t mind! When you all think about API versioning, what makes the most sense to you — a semver approach (major.minor.patch) a la NPM, or a date-based approach (2020-01-07) a la AWS? Or is some combination of the two desirable? A…
I do not know any advantage of date-based versioning, other than someone knowing how new it is. Semver is important for knowing whether or not to evaluate for breakages. You can theoretically combine both of these by making the date the patch version or supplying it as a version metadata
> I do not know any advantage of date-based versioning
It can be very useful for continuous improvement and handling forward compatibility. Here's how Stripe do it:https://stripe.com/en-fr/blog/api-versioning, we found that very convenient.
Re: How Shopify Manages API Versioning and Breaking Changes
#8Hi everyone. As the founder of an API company, this article has me wondering about the semantics of versioning — so I thought I’d ask the community a question. I hope the Shopify API team doesn’t mind! When you all think about API versioning, what makes the most sense to you — a semver approach (major.minor.patch) a la NPM, or a date-based approach (2020-01-07) a la AWS? Or is some combination of the two desirable? A…
I do not know any advantage of date-based versioning, other than someone knowing how new it is. Semver is important for knowing whether or not to evaluate for breakages. You can theoretically combine both of these by making the date the patch version or supplying it as a version metadata
I think it’s the implied stability, especially for long-standing APIs. S3’s API is 2006-03-01 — meaning there haven’t been breaking changes in over 13 years. This creates a psychological contract with developers that nothing’s changing anytime soon.
The trade off is that AWS has some godawful APIs (DynamoDB has the least intuitive API I have ever worked with). But they’re stable.
If you go with a date-based approach and create a process + contract whereby you guarantee API stability and / or deprecation date, the developer always knows exactly how much time they have before an upgrade.
Re: How Shopify Manages API Versioning and Breaking Changes
#9Hi everyone. As the founder of an API company, this article has me wondering about the semantics of versioning — so I thought I’d ask the community a question. I hope the Shopify API team doesn’t mind! When you all think about API versioning, what makes the most sense to you — a semver approach (major.minor.patch) a la NPM, or a date-based approach (2020-01-07) a la AWS? Or is some combination of the two desirable? A…
My impression is that semver makes far more sense for published libraries (DLLs or ruby gems or npm packages etc) while date-based makes far more sense for SaaS APIs. The constraints and usage patterns are fairly different between the two.
Re: How Shopify Manages API Versioning and Breaking Changes
#10It's interesting to compare and contrast this method of API management with Stripe. As far as I understand, the Stripe api would continue to work indefinitely so long as you lock your api version, whereas Shopify would eventually break the app as they essentially backport breaking changes to older api versions. Initially, I thought Stripe's method was superior, and would provide the best API experience, but realized…
Funny that you mention Stripe, because it was definitely the canonical backwards compatibility API for me.
... Until just recently in mid Nov they changed some behavior that caused us to double/triple/quadruple charge customers unintentionally in some not-so-uncommon edge cases... I’m still trying to square this one with their support, so details are a bit thin. But definitely a big surprise for me to see this happening when previously I never imagined something like this can happen given the API versioning stability.