[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

[nozzlegear]

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

[hn_throwaway_99]

To be honest, when I read about these types of difficulties in managing changes in an API over time, I really wonder why more companies don't go over whole hog into GraphQL. GraphQL won't solve all your problems (sometimes changes are breaking because business needs require it), but GraphQL provides a better scheme for API evolution than any other API toolkit I've used:

1. You can just keep adding new methods and fields as needed, but since each client asks only for the fields specific to what they want, you don't get big bloated response objects.

2. Lots of times your breaking changes only differ slightly from previous versions, and the way GraphQL resolvers are written makes it really easy to refactor things into one base method that both the old and new versions can share.

3. Proper use of the @deprecated schema directive means your doc is 'clean' by always showing the latest version that new users should adopt, but the doc is still there for users on older versions.

4. It's really easy to add logging and tracing in your resolvers to see how often fields are being accessed and who is using them. At some point you may decide to break backwards compatibility by deleting old fields, but you'll know exactly who you are breaking.