Simplicity Trap indeed.

Overly simplistic examples ignore real-world challenges (as well as well-established real-world solutions), which can lead to poor solutions (and advice), for example: breaking changes. This is the same way that people get sucked into repository pattern. <shudder>

In making the case for stable URIs, e.g. /products, based on a trivial and technically non-breaking change example, you seem to ignore breaking changes that can (and often do) include changes to required attributes. These changes are not only externally required, e.g. GDPR, they usually result from new requirements from the business.

GETing the product with a new "price" attribute may not break anything, but POSTing one without a price is likely to break things. So versioning is necessary. The question is how best to do it.

Others have pointed out that versioning URIs does not actually break REST (or "violate" its principles), which is a style, not a standard. "Timeless" URIs is your preference, but I'm not convinced that it's the best way.

The "easier maintenance"/"version clutter" straw man example ignores the need to end-of-life older endpoints -- a common real-world challenge. Staying current should be a condition in the API's terms of use.

Others have also pointed out that versioning with request headers is arguably more difficult and error prone and does not in any way remove the need for code changes in the back end.

Using custom media types is a creative but even more unusual solution, which if anything is even more prone to client misconfiguration and confusion. If clients bookmark /products but are unaware (or forget) that valid requests must include "hidden" or "cryptic" headers and values, how is this better than bookmarking endpoints with explicit, very visible and clear versioning?

Nicolas Fränkel reminds us in his reply that API gateways exist and are one time-tested and widely-accepted solution. He also reminds us that querystring parameters are another alternative for versioning.

To me, API gateways seem to provide a much more flexible mechanism for versioning, as well as for gently migrating clients from one version to another, using configuration settings rather than code changes.

Paired with a more careful and consistent approach to entity modeling, e.g. "UnitPriceInUsd" (more descriptive and accurate), which can reduce the number of breaking changes and therefore the need for frequent versioning, any of these versioning strategies can be effective.

I don't think you've successfully made the case that explicit, path variable versioning, e.g. /products/v1, is "messing up" anyone's API versioning, but I do appreciate the transparency and reader credit in your "From other developers" appendix.

Thanks for a thought-provoking article. I hope that I've demonstrated that overly simplistic examples can lead to problems.