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?
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. =)
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.