Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How Shopify Manages API Versioning and Breaking Changes

engineering.shopify.com

Post reply on HN
Print view View original

31–40 of 95 posts

Re: How Shopify Manages API Versioning and Breaking Changes

#31

Post by keithwhor »

seelmobile wrote: post #30
keithwhor wrote: post #2

Hi 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…

(Disclosure: I work at Google on public APIs, opinions are my own) Google's proposed a "stability" semantic as a third option[0]. TL;DR no breaking changes in the Stable channel but you can add backwards-compatible[1] features in-place. A permanent Beta channel that's a superset of Stable lets users choose how change-tolerant they are. This lets API producers launch features earlier, knowing they will only impact ris…

Do you think it’s possible to achieve the same sort of system by just using semver + release candidates?

For example, 5.x.x is currently stable, so you release 6.0.0-rc1 (2, 3, ...)?

Re: How Shopify Manages API Versioning and Breaking Changes

#32

Post by MentallyRetired »

mmmannn wrote: post #22
MentallyRetired wrote: post #16

Shopify made a change to their API that was easily measurable on who it would affect, but didn't email us. Refused to grant us a temporary exemption (they would do it for $2000/m they said). The end result? They've sunk my business. I've replaced shopify now by writing my own but it's too late. My customers have all gone to my competitors and we're looking at pivoting.

What was the change? AFAIK Shopify would never give a temporary exemption for money, that's very much against their philosophy as a SaaS. Either you provide accurate details or this is just FUD.

It was a limitation on the number of variants. They had no limits prior to this API update I'm talking about. My business allowed people to create merch and we'd add it to a collection on our storefront. Developer support told us sometimes they grant temporary exemptions. They did not. They told us we could upgrade to shopify plus which has no such limitations, but being a bootstrapped company we couldn't swing the $2k per month.

Edit: Just to be clear, it was always on our roadmap to migrate away from Shopify's platform, but they accelerated our timeline and we had to limit the amount of merch our customers could add which obviously led to upset customers.

We're still operating, albeit close to insolvent, and have since launched our new platform. But our reputation has been irreversibly damaged.

Re: How Shopify Manages API Versioning and Breaking Changes

#33

Post by setr »

keithwhor wrote: post #25
Waterluvian wrote: post #23

Earlier quoted context omitted.

I don't think there's one right answer, but my opinion is: - Treat APIs as immutable. - Any mutation results in a wholly new API version, not a patch or minor update. - The developer will learn what changed, and how much changed by reading the patchnotes, not looking at which semver numbers changed. This is probably a healthy practice to encourage. - Don't change APIs so much. The interface should be very carefully d…

I don’t disagree with your assessment on semver as it currently exists for, say, NPM packages. I do think that with web APIs specifically, the surface area is a lot smaller — the HTTP interface is literally all you touch — so semver, in its purest form, is actually completely enforceable as long as you understand the API schema. Our team has talked a lot about either hard-enforcing or automatically applying semver wh…

Tbh, it doesn't matter. But the semantics should be such that it doesn't matter -- the user of the API shouldn't care whether it's implementation bounded or not. But Everytime you break that abstraction, trust in the abstraction is necessarily reduced.

Bounding to implementation is just the easiest way out -- if your policies, tests and protocols consistently fail to uphold that abstraction, then the you can fallback to this very simple (presumably innefficient) strategy to do so.

But I, as a dev, just want a stable API, and I don't care how it's done.

Re: How Shopify Manages API Versioning and Breaking Changes

#34

Post by Waterluvian »

keithwhor wrote: post #25
Waterluvian wrote: post #23

Earlier quoted context omitted.

I don't think there's one right answer, but my opinion is: - Treat APIs as immutable. - Any mutation results in a wholly new API version, not a patch or minor update. - The developer will learn what changed, and how much changed by reading the patchnotes, not looking at which semver numbers changed. This is probably a healthy practice to encourage. - Don't change APIs so much. The interface should be very carefully d…

I don’t disagree with your assessment on semver as it currently exists for, say, NPM packages. I do think that with web APIs specifically, the surface area is a lot smaller — the HTTP interface is literally all you touch — so semver, in its purest form, is actually completely enforceable as long as you understand the API schema. Our team has talked a lot about either hard-enforcing or automatically applying semver wh…

I don't really trust semver insofar as there's nothing to trust, in my opinion. What am I trusting? That I don't have to understand what changed and can take semver's word for it? To me, personally, that's an abdication of my responsibility to know what I'm utilizing and implementing against.

What's the practical value you're hoping to gain by hard-enforcing semver, especially if the surface area of HTTP APIs is a lot smaller? And this isn't a loaded question. I might just not be privy to your team's needs.

Also consider (and this again falls within the realm of personal opinion) the value of achieving _maximum possible statelessness_ as a developer. If I'm reading you right, you're asking me to know and remember, and probably write down somewhere, that your API's versioning means something different than others. So I now have another branching path to maintain: how to behave when your API changes. What I like about the simple numbered API schema is that I can come back to the API usage in a stateless manner. I just see that the number is different and I know what to do: learn what changed and decide if I have to act on it. Of course I could do this by looking at a semver as a unique identifier without semantic meaning, but that kind of leads to my initial point: encourage best practice by not giving the developer a semantic shortcut to which they can abdicate responsibility.

Re: How Shopify Manages API Versioning and Breaking Changes

#35

Post by thdrdt »

keithwhor wrote: post #6
thdrdt wrote: post #5

Earlier quoted context omitted.

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?

It's not about trusting a company. It's about wanting to know what will break if you start using a newer version of an API.

And sometimes you also discover new features that can be really useful.

Re: How Shopify Manages API Versioning and Breaking Changes

#36

Post by asdkhadsj »

Waterluvian wrote: post #23
keithwhor wrote: post #2

Hi 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 don't think there's one right answer, but my opinion is: - Treat APIs as immutable. - Any mutation results in a wholly new API version, not a patch or minor update. - The developer will learn what changed, and how much changed by reading the patchnotes, not looking at which semver numbers changed. This is probably a healthy practice to encourage. - Don't change APIs so much. The interface should be very carefully d…

What does a codebase look like with these API versioning exactly?

I feel like code bloat would be hard to maintain. Obviously I could take two endpoint handlers that have the same functionality and move their behavior into a shared function, but there's also tests to consider. As time went on, I'd have a pile of tests running against seemingly random versions.

Eg, `test_blog_create()` might test v1 and v2 of the API as that specific endpoint didn't change, but suddenly in v3 the API _does_ change, so now I need to write a slightly different test to handle that new functionality. `test_blog_create_v3()` or w/e.

I'm not arguing against it, merely noting what I've previously thought about as problematic for implementing versioned APIs.

Thoughts on how best to manage the code base?

Re: How Shopify Manages API Versioning and Breaking Changes

#37

Post by ahnick »

eapache wrote: post #19
keithwhor wrote: post #12

Earlier quoted context omitted.

What specifically about SaaS API constraints do you think makes a date-based approach more appealing than semver? My high-level feeling is that it’s just way more difficult to ship a SaaS API than a Ruby Gem, so adding semver to that is just another layer of API management everybody has to agree on. Do you agree with this assessment?

For most published libraries every old version is always available and upgrading is never mandatory. For SaaS APIs the constraints of the business means that very few businesses (Stripe being the notable exception) want to support more than a handful of versions at a time, which results in versions regularly reaching end-of-life and completely disappearing. In this world, upgrading to newer APIs is mandatory and fair…

> "SaaS APIs need a form that makes it easy to infer support windows and end-of-life status."

You can infer that from the Release Date though. (e.g. Version 3.4.2 Released on 2019-12-17) To me the power of Semver is that it conveys complex relations between version iterations.

For example:

- 3.4.1 -> 3.4.2 is just fixing bugs in existing functionality

- 3.4.2 -> 3.5.0 is an upgrade containing non-breaking changes

- 3.5.0 -> 4.0.0 is an upgrade containing breaking changes

As a developer, Semver + release date seems to convey everything date based versioning does plus I get the advantage of understanding at glance the importance and risk profile of each release.

Note, this system does not reduce my obligation to run my own tests to verify that the version has in fact lived up to its intention (i.e. a minor version bump did not introduce a breaking change). Even though my obligation is not reduced, it does act as a filter to help prioritize development time for evaluation of performing upgrades.

Re: How Shopify Manages API Versioning and Breaking Changes

#38

Post by gregmac »

thdrdt wrote: post #5
keithwhor wrote: post #2

Hi 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.

> Both don't say much without good changelog.

This is a good point. Good changelogs, like any documentation, take a lot of effort and so are unfortunately quite rare.

As an API consumer, to me the ideal upgrade-related documentation includes:

* Detailed release notes for each released version

* For non-GA releases like alpha/beta/RC's, describe the changes since the last small release -- typically consumers of a beta are following dev quite closely

* For GA releases, pretend the alpha/beta/etc don't exist at all. Describe the delta from the last GA release. Consumers don't care about the fix for a bug in a beta they never even knew existed.

* When you do breaking changes, provide upgrade guidance, like "If you were doing x before, now you should do y + z instead"

* If appropriate, consider also keeping separate upgrade guidance documentation for major breaking changes, for those laggard consumers that are going from a much older version like 2.x to 4.x. This allows someone to follow more of a checklist to get up-to-date without having to read 900 pages of individual release notes

You can do this with date-based version, but it's much harder as a consumer to figure out unless there's very good documentation. If I'm upgrading from "2.0.4" to "4.1.1", I know as a absolute minimum starting point I will be looking at release notes for "3.0" and "4.0" and from that, I should get a pretty good sense of the overall effort involved. If I'm upgrading from "2016-11-05" to "2019-12-19", how do I do the equivalent evaluation?

Re: How Shopify Manages API Versioning and Breaking Changes

#39

Post by keithwhor »

Waterluvian wrote: post #34
keithwhor wrote: post #25

Earlier quoted context omitted.

I don’t disagree with your assessment on semver as it currently exists for, say, NPM packages. I do think that with web APIs specifically, the surface area is a lot smaller — the HTTP interface is literally all you touch — so semver, in its purest form, is actually completely enforceable as long as you understand the API schema. Our team has talked a lot about either hard-enforcing or automatically applying semver wh…

I don't really trust semver insofar as there's nothing to trust, in my opinion. What am I trusting? That I don't have to understand what changed and can take semver's word for it? To me, personally, that's an abdication of my responsibility to know what I'm utilizing and implementing against. What's the practical value you're hoping to gain by hard-enforcing semver, especially if the surface area of HTTP APIs is a lo…

I think you misunderstand where I’m coming from with my line of questioning.

I’m asking questions because we provide tools that standardize the API development experience. Semver is trustable if the tools create the contract instead of the developer that decides to build the API. We deliver the tools that create the contract.

In this sense, APIs built and delivered atop our platform don’t need to “encourage best practice,” best practice is — or at least can be — hardcoded in with no potential for footguns.

Your concerns about semver are well-founded. I’m asking questions because I’m pondering aloud if we can fix them and change semver — with respect to APIs — from a social contract to a coded contract, and include tools necessary to inform end-users of API changes. :)

Does that make more sense?

Re: How Shopify Manages API Versioning and Breaking Changes

#40

Post by k__ »

tclancy wrote: post #26
k__ wrote: post #11

Earlier quoted context omitted.

I never understood why we settled on semver. If I have a bug, it's a breaking change. If I fix this bug, it's also a breaking change.

Your presumption of a collective "we" is at the root of the problem: versioning is one of those things in development where the same word can mean very different things to different people (see also: agile, automated testing). Prior to semantic versioning, there was an approach that looked like an agreed-upon standard to consumers of software packages/ libraries/ APIs but was not. On one extreme you had certain devel…

True.

Semver is like unsound type systems or TDD, most of the time it's okay, until it isn't.

Post reply on HN