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

11–20 of 95 posts

Re: How Shopify Manages API Versioning and Breaking Changes

#11

Post by k__ »

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.

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.

Re: How Shopify Manages API Versioning and Breaking Changes

#12

Post by keithwhor »

eapache wrote: post #9
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…

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.

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?

Re: How Shopify Manages API Versioning and Breaking Changes

#13

Post by m12k »

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 prefer semver, but it's still not exactly what I want. What I'm looking for is the answer to 'how painful/risky is upgrading likely to be?'. I expect an x.x.1 release to be zero/low risk - small fixes only within current api and contract. I expect a 2.x.x release to come with major risk of breakage (and I'll almost always want to wait for 2.0.2-2.0.3 before actually upgrading - and I expect a 1.x.x -> 2.x.x release to have a risk of bigger changes compared to a 5.x.x -> 6.x.x since the latter is expected to have the fundamentals ironed out by now). But there doesn't seem to be much consensus on whether an x.1.x release can have breaking changes or not - or maybe they don't come with as strict a definition of a breaking change as Shopify is using - so I'm left with treating them the same as 2.x.x (though usually I don't wait for x.x.1 in this case).

Re: How Shopify Manages API Versioning and Breaking Changes

#14

Post by keithwhor »

m12k wrote: post #13
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 prefer semver, but it's still not exactly what I want. What I'm looking for is the answer to 'how painful/risky is upgrading likely to be?'. I expect an x.x.1 release to be zero/low risk - small fixes only within current api and contract. I expect a 2.x.x release to come with major risk of breakage (and I'll almost always want to wait for 2.0.2-2.0.3 before actually upgrading - and I expect a 1.x.x -> 2.x.x release…

Would a tool that easily shows you documentation / schema changes between API versions be useful to you, or create more trust with a SaaS provider if they offered it?

Re: How Shopify Manages API Versioning and Breaking Changes

#15

Post by kenrose »

eapache wrote: post #9
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…

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.

One challenge with date based is that it can make your API seem old if it’s really stable. For example, see PagerDuty’s v1 events API:

https://events.pagerduty.com/generic/2010-04-15/create_event...

Customers there would sometimes ask if that API was still relevant given its date is 9+ years old.

In Shopify’s case, where there are quarterly version bumps and deprecation over time, date based makes better sense.

Re: How Shopify Manages API Versioning and Breaking Changes

#16

Post by MentallyRetired »

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.

Re: How Shopify Manages API Versioning and Breaking Changes

#17

Post by Waterluvian »

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.

I would love to read more about this case study on how an API change by a business service sinks a business.

Re: How Shopify Manages API Versioning and Breaking Changes

#18

Post by thsowers »

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.

> Shopify made a change to their API that was easily measurable on who it would affect

What was the change?

Re: How Shopify Manages API Versioning and Breaking Changes

#19

Post by eapache »

keithwhor wrote: post #12
eapache wrote: post #9

Earlier quoted context omitted.

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.

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 fairly frequent.

The result is that API version handles need to prioritize different information. Libraries need a format that makes it easy to ballpark the size of changes between arbitrary not-strictly-sequential versions. SaaS APIs need a form that makes it easy to infer support windows and end-of-life status.

Re: How Shopify Manages API Versioning and Breaking Changes

#20

Post by joegahona »

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.

> The end result? They've sunk my business.

What was the business?

Post reply on HN