A thousand times this. Not just in API versioning, but in everything.
Every new thing you introduce is a thing you must first develop competency in, and then maintain competency in for the life of the project. This cost is paid during development, it's paid on every new hire onto that project, and it's paid on-going as you need to work with that tool and have your ops team deploy, manage, debug, and tune that tool (where applicable).
Choose boring technology where possible if it's not directly related to your line of business.
Don't even get me started on microservices. If your company name isn't Amazon or Google, then what are you even doing? Just don't. One company I worked at did microservices. They never had enough headcount to actually do things properly. Every single service was this half-assed API that followed the current trend-of-the-day. Looking at the microservices was like looking at the rings of a tree. You could tell when certain people joined or left a company or when they decided to experiment with Clojure or Elixir or GraphQL, etc. Each service required a different header incantation to get it to work properly. You couldn't just curl a URL because that would be way too sensible. I wrote my own curl wrapper just to deal with this bullshit.
And of course the biggest problem with microservices is that documentation is horrid. There is no incentive to maintain good documentation because the APIs are internal. I've spent many nights staring at the internals of various microservices to decipher what they are doing. It's not even my code or my department. But I'm stuck sifting through other people's messes.
Oh, and it's really really cute that developers still believe in the mechanical documentation fairy that extracts documentation from the code with some geewhiz tool. No, GraphiQL is not documentation. Stop lying to yourself and each other.
> Please don't use gRPC
gRPC is another bandwagon. The gRPC proxies must be made out of paper mache with how quickly they crumble under the slightest load.
While there are many right ways to version, there are also a few wrong ones. Like putting the version in a header.
I'm sure that's specified somewhere, but it's a shamefully stupid specification, so don't follow it. Any sane person reading that is going to think you're accepting a specific version of JSON.
Also, if you must put versions be in a header, STOP with the nonsense of pretending things don't exist. Give us some freaking clue, return a 404 and explain that we're missing your stupid header, or that the planets haven't aligned, or whatever we're supposed to fix.
* Have to set up response headers and caching carefully to make sure different versions are cached separately.
* A bit of extra complexity to set up load balancing.
* A bit of extra complexity to set up web framework routing to controllers.
* A bit of extra complexity for logging to track which endpoints were called.
* Calling the URL without specifying a version gets you some undefined version...
* ... or if you require a version header, can't preview GET endpoints in a standard browser.
* If different parts of the API have different latest versions, you can't encode it in an URL and therefore can't return URLs for linking between resources.
* On major version changes you might be removing, renaming or moving URLs, so why keep them pure and versionless in the first place.
The complexity of dealing with headers seems easier than the complexity of routing constantly changing urls.
How often are your APIs changing incompatibly anyway?
When they do changing the URL should dwarf next to changing the surrounding code to the new data model. If that's not the case then what was the point of the upgrade?
"...it will be much easier to run analytics on usage from web access logs..."
Headers don't normally get logged the way that URLs do. Having easy and cheap analytics is very helpful in making the right calls. "Expensive" analytics is really painful with APIs because some people rightfully get scared about the impact of making changes while others will just plow ahead.
We need to strive to make an API obvious and "immutable" (i.e. under one path you get one specific behavior). This in affect means the good old boring /v2/ in the URL path tends to be best if you can't keep everything under one roof by deprecating/removing/introducing single endpoints in the initial version (due to lots of name collisions).
You should plan your API to be backwards-compatible, plan major version changes about 2 years apart, and put the sunset time of your version in big bold red lettering on the front of your docs. That still may not stop clients from begging for longer support, so again, the more backwards-compatible you are, the less of a pain in the ass it is to abandon old versions. And for God's sake, have the developers consider the pain of customer migration when they develop the new versions, and provide clear, feature-complete migration paths from the old version to the new.
Plan on using a single non-Apex hostname (and possibly region-specific) for all your APIs, and do not change it, because again, pain of support/migration. Then put the version number in the URL, because it will be much easier to run analytics on usage from web access logs, and it works better with a shared domain. With this scheme you can always have a reverse proxy redirect specific URI prefixes to completely different backends. For simplicity, make each new major API version a fork, and run it as a separate set of backend network services.
Please make all of your teams follow the same API conventions. Don't make me write 5 different API calls 5 different ways because you had 5 teams that didn't work together. When I see APIs like this, I know the company's tech management are lazy morons, which means the rest of leadership probably is too.
Being backwards-compatible is different from evolving API functionality. If you just evolve everything, eventually you will reach a high level of complexity for each call that requires massive flow charts to decipher. It's better to create entirely new functions that are simpler to reason about. But don't do this if you can wait for the next major version and consolidate functionality then.
Make sure you follow good distributed computing practices, like giving clear error messages when your server is too busy and the client needs to enable an exponential backoff with jitter.
Please don't use gRPC, for the love of God. It's not compatible with every other API out there that (today, anyway) uses HTTP. The fact that there are multiple "gRPC proxies" is proof enough that an incompatible interface is just a future pain in the ass. Project owners / managers / team leads: Don't let developers pick the technology just because they think it's cool or modern or the best practice, and definitely don't let them choose something they've never used in production before. Consider the actual cost of the thing long-term to your organization.