News for hackers. Stuff that matters.
Re:How Shopify Manages API Versioning and Breaking Changes by Waterluvian on Thursday December 19, 2019 @10:42AM (#21835819)
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 by keithwhor on Thursday December 19, 2019 @10:53AM (#21835949)
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 by Waterluvian on Thursday December 19, 2019 @10:58AM (#21836001)
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. =)