The most underrated question in API versioning is not "how do we version?".
It is "how do we know when it is safe to delete the old version?"
A lot of teams treat version removal as a calendar event.
The sunset date arrives, somebody opens a pull request to delete v1, and nobody really checks if the world is ready.
Sometimes it works.
Sometimes it takes down a key partner integration on a Friday afternoon.
The difference between those two outcomes is rarely the code.
It is the data you collected before pressing delete. A simple but effective practice is to track three things during the deprecation period.
First, what percentage of total requests still hit v1.
Second, which clients or API keys are responsible for that traffic.
Third, which specific endpoints on v1 are still being used.
With those three numbers, "should we remove v1?" stops being a debate and starts being a decision.
If 2% of traffic still uses v1 and it is all coming from one internal team, you know exactly who to talk to.
If 30% of traffic still uses v1 and it comes from twenty different consumers, you are not ready, no matter what the calendar says.
The teams that do this well usually define removal thresholds upfront. Something like: "we remove a major version only when its traffic stays under 5% for 30 consecutive days, and no top-10 consumer is still on it."
That kind of rule removes emotion and politics from the conversation. It also gives consumer teams a clear target. They know exactly what "done" looks like.
There is one more benefit that is easy to miss.
When you base removal on telemetry, your communication with customers improves. Instead of saying "we are removing v1 on this date, please migrate", you can say "you are currently using v1 on these specific endpoints, here is the migration guide for each of them."
That level of specificity dramatically increases the chance that the migration actually happens on time.
Version removal is a production event, not a cleanup task.
Treat it like a release, with data, monitoring, and a rollback plan, and it will stop being scary.
I cover the full decision framework and examples here:
thecodeman.net/posts/why-do-…
__
📌 Join the Newsletter and get "AI in .NET" Starter Kit projects for free:
thecodeman.net
♻️ Repost to others.
📂 You can save this post for later, and you should do it.
➕ Follow me to learn .NET and Architecture every day.