Home / Knowledge hub / API versioning
Knowledge hub
API versioning
Running old and new API versions together, and the security gaps the old ones keep.
What it means
API versioning is how you change an API without breaking the apps that already use it. You publish the new behaviour under a new version, often /v2/ in the address or a header, and keep the old one running until clients have moved.
The trouble is the word keep. Old versions stay deployed long after the team has stopped thinking about them, and they were built with the checks, libraries and assumptions of their time. Few people remember what they expose, and fewer test it.
Why it matters
A security fix applied to /v2/ does not reach /v1/ unless someone also changes /v1/, and nothing forces that to happen. An attacker who finds that the old route still answers can use the original flaw, which is why a fixed problem sometimes reappears. Old versions may also quietly lack newer rate limits, logging and field filtering that the current version has.
From a business view, this is exposure you did not choose and may not know about. Customer data can be reachable through a route no one monitors, and an audit or customer review can fail on something that the current documentation never even mentions.
How it shows up
You meet old versions as /v1/ or /api/legacy/ routes, as mobile app versions that cannot be updated, and as partner integrations nobody dares to switch off. The OWASP API Security list calls the underlying problem improper inventory management, because deprecated versions stay live without anyone owning them.
Keep a list of every version in use, set a retirement date and tell clients, and monitor traffic to see who still calls the old ones. Until then, apply the same fixes and limits to old versions as to new. Test them directly. See API inventory and zombie APIs.
Questions people ask
API versioning, answered
Do old API versions need the same security as new ones?
Yes. If they are reachable and handle real data, they need the same authorisation checks, limits and logging.
Treat a live old version as part of your attack surface, not as history.
Why do old versions keep old vulnerabilities?
Because fixes are written for the code being developed. Unless the fix is ported, the old branch keeps the flaw.
Teams often only discover this when a retest passes on the new version and fails on the old.
How do we retire an API version safely?
Announce a date, watch who still calls it, contact the owners of remaining traffic, then switch it off and confirm it no longer answers.
Return a clear error instead of silently redirecting, so remaining clients notice.
Should the version go in the URL or a header?
Either can work. The URL is simple to see and log. A header keeps addresses tidy.
For security, what matters is that you can list and test every version, whichever method you pick.
How do we find versions we forgot?
Compare your code, gateway configuration, documentation and real traffic. Try guessing neighbouring version numbers on your own endpoints.
Anything that answers but is not on your list needs an owner or removal.
Sources
Where this comes from
Related
Terms that sit next to this one
API inventory
A maintained list of every API you expose, who owns it and what it returns.
Zombie API
An old API version that should be retired but still answers requests.
Shadow API
An API running in production that nobody has documented, tracked or secured.
Regression
A bug that was fixed and has come back, usually undone by a later change.
Patching
Applying the fixes that vendors and maintainers publish.
Is the old route still open?
Fixes are often applied to the new route and missed on the old one. We test the versions that answer, including ones you forgot, and prove the result with the exact request. Book a pilot on one app.
Or start with a $199 pilot on one application: thirty days, success criteria agreed before day one, credited against the annual if you convert.