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

41–50 of 95 posts

Re: How Shopify Manages API Versioning and Breaking Changes

#41

Post by Waterluvian »

keithwhor wrote: post #39
Waterluvian wrote: post #34

Earlier quoted context omitted.

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

Yeah it does. Thanks for clarifying. I think there's a very complex conversation to be had here, especially since you're working on a meta-level of tooling to ease API development.

With two days before my first vacation of the year, my brain is a pile of mush. I'm going to politely and apologetically bow out of this conversation. =)

Re: How Shopify Manages API Versioning and Breaking Changes

#42

Post by keithwhor »

thdrdt wrote: post #35
keithwhor wrote: post #6

Earlier quoted context omitted.

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.

That’s fair! From my perspective that’s something that’s building trust with the SaaS provider. We’ve all heard, “ugh! This API is so shitty!” before — I’m fascinated by what tools and products can be built to prevent developers from feeling these pains.

Thanks for the feedback. Can definitely see that changelogs are really underinvested in across the industry, and it’s useful to have people mention how valuable they are.

Re: How Shopify Manages API Versioning and Breaking Changes

#43

Post by Waterluvian »

asdkhadsj wrote: post #36
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…

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…

Versioning is hard. Versioned APIs are very hard. I'm in an especially tricky spot because we've got customers that might refuse to upgrade our product for years and years, if ever.

Two approaches I've taken, with a blogpost worth of thoughts on them:

1. Every version is a whole new database/webserver stack. You shut the oldest one down when the last customer migrates off it. The bloat is real, but it's dead simple and it works.

2. A single database with a webserver that exposes all the versions. The contract is that the database shall not undergo destructive migrations. Only additive migrations. Or if you must, modify schema in a way that you can deterministically generate every previous API's view. Again, discard older versions when the last customer has been migrated off.

I'm sure you can immediately smell some problems with either of these approaches. Sacrifices are definitely made.

Re: How Shopify Manages API Versioning and Breaking Changes

#44

Post by wongarsu »

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 think semver is easily enforceable. Take for example the discussion in this thread about stripe changing the order in which hooks fired, which completely changed the meaning of a null value in the next_payment_attempt field. Just looking at a traditional API schema wouldn't reveal any change, yet this was a major breaking change to some. Maybe you can create an API schema which encompasses the order in which hooks fire, but that still doesn't help if somebody changes the semantics of a field without changing its name or type.

Re: How Shopify Manages API Versioning and Breaking Changes

#45

Post by xal »

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.

Can you share more details? I run Shopify and that's not something we would do.

Re: How Shopify Manages API Versioning and Breaking Changes

#46

Post by circular_logic »

Glad to see that Shopify has better API versioning on their mind. When I used there API a few years ago, it was one of the worst APIs to depend on. To the point, we had to architect our system to alert us for unannounced breaking API changes so we could fix and replay the JSON back.

- Moving JSON fields in and out of nestings didn't seem to be counted as a breaking change.

- Changes were rarely announced, and there was never a changelog as to what had changed (they look to have started one starting 2018 [1])

- When we contacted support about a brake, they would often be surprised.

- Often the only sign there would be a change would be that new fields would start to show up before a larger change.

All this would happen every few months. Reading this article I can start to see the reasons why this was happening.

[1] https://developers.shopify.com/changelog?filter=all

Re: How Shopify Manages API Versioning and Breaking Changes

#47

Post by rudasn »

gingerlime wrote: post #10
Judson wrote: post #3

It'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 happen…

Not sure if this helps but there was an issue with chrome submitting forms multiple times recently. It has been fixed in the recent 79 release.

Re: How Shopify Manages API Versioning and Breaking Changes

#48

Post by nozzlegear »

circular_logic wrote: post #46

Glad to see that Shopify has better API versioning on their mind. When I used there API a few years ago, it was one of the worst APIs to depend on. To the point, we had to architect our system to alert us for unannounced breaking API changes so we could fix and replay the JSON back. - Moving JSON fields in and out of nestings didn't seem to be counted as a breaking change. - Changes were rarely announced, and there w…

I maintain a Shopify API package for .NET [0] and this has largely been my experience as well. Their attitude toward breaking API changes has caused me a good deal of frustration in the past. To make matters worse, their docs weren't (and still aren't, in my opinion) that great; my biggest complaint being they typically don't document when values can be null or even have a different type (e.g. property X could be a string or a decimal, but you'll never know looking at their docs).

This has led me to taking the drastic step of making _every_ property nullable. It's gross and feels bad to use, but at least it prevents JSON parse operations from crashing applications when a value is unexpectedly null.

[0]: https://github.com/nozzlegear/shopifysharp

Post reply on HN