Version one of your API is probably still answering requests. It was left running so a mobile app could catch up, the mobile app was replaced, and nobody switched the old version off because nothing was obviously broken. Improper inventory management sits at number nine in the OWASP API Security Top 10 for 2023, and old versions are the clearest example of it.
Why old versions are weaker than new ones
Security improvements land in the version being developed, not in the one being kept alive. When a team adds object level authorisation checks after a review, those checks go into version two. Rate limiting gets configured on the new routes. Logging is improved where the traffic is. The old version keeps its original behaviour, which is why an attacker who finds it often gets a better result than they would from the current API. The data behind both is usually the same database, so a weaker path to the same records is all the attacker needs.
Building an inventory you can trust
You cannot retire what you cannot list, so start by finding every version and environment that answers. Gateway configuration and DNS records give you a first pass, and access logs give you the truth, including calls to routes that never appeared in documentation. Include non-production environments in the inventory, because a staging API on a public hostname with production data behind it is a common and painful finding. Record who owns each version, what its authentication model is, and which clients still call it, since that last figure decides how quickly you can turn it off.
“The question I ask on every API job is which versions exist, and the answer never matches the logs. Somebody always says version one was decommissioned, and then we find it responding on a hostname the load balancer still routes. Check by request rather than by memory, because a route that answers is in scope for an attacker whether or not it is in your documentation.”
William Fieldhouse, Director, Aardwolf Security Ltd
Retiring a version without breaking customers
Deprecation works when it is measured rather than announced. Instrument the old version so you know exactly which clients call it and how often, then contact those clients with a date. Return a Sunset header and a deprecation notice so automated consumers see the warning in the response. Introduce short outages, sometimes called brownouts, so integrators notice before the final switch-off. When the traffic reaches zero, block the routes at the gateway before removing the code, since that is reversible in seconds if you have missed someone.
Keeping the problem from returning
Make version retirement part of the release process rather than a project. Set a supported version policy, commonly the current version and one previous, and write the end date into the documentation when a version launches. Include every live version in the scope of your API security assessments, not just the current one, because testing only the newest version is how these findings survive for years. When comparing penetration testing providers, ask how they enumerate endpoints, since a tester who works purely from your specification will see the API you meant to publish rather than the one you did.
Frequently asked questions about API versioning
These come up whenever a platform team plans a deprecation.
How long should an old version stay available?
Long enough for your slowest integrator, which is usually six to twelve months for business customers. Set the date at launch, because open-ended support is what leads to a decade-old version still answering.
Does versioning by header help?
It keeps URLs tidy and makes discovery harder for you as well as for an attacker. Whichever scheme you choose, the inventory and the retirement process matter far more than the mechanism.
