Cybersecurity glossary
What is API Versioning?
Learn what API versioning is, how URI header and media-type versioning differ, how to retire old versions safely, and which security risks appear when deprecated APIs linger.
Definition
API versioning is the practice of explicitly evolving an API contract across incompatible or significant changes so clients can adopt new behavior on a controlled timeline while older versions remain supported, monitored, and eventually retired.
Why API versioning matters
APIs are contracts with strangers—mobile apps, partners, and scripts you do not control. API versioning lets those contracts evolve without a big-bang break, while giving security and platform teams a way to sunset unsafe legacy behavior.
Without versioning discipline, every “temporary” compatibility shim becomes permanent attack surface.
Common versioning approaches
URI path versions
Expose /v1 and /v2 routes that are easy to see in logs and docs.
Header versions
Clients send an API-Version header while paths stay stable.
Media-type versions
Content negotiation selects representation versions via Accept.
Additive evolution
Prefer non-breaking additions inside a version when possible.
A practical version lifecycle
Detect a breaking need
Security hardening or product change cannot stay compatible.
Publish the new version
Ship vNext with docs, examples, and migration notes.
Run versions in parallel
Support N-1 with monitoring while clients migrate.
Deprecate with dates
Announce end-of-life and communicate in headers/changelogs.
Block new adoption of legacy
Stop issuing credentials or onboarding that targets retired versions.
Retire and remove
Disable routes, confirm zero traffic, and delete code paths.
Security impact of poor versioning
| Failure | Security risk |
|---|---|
| Forever-lived v1 | Unpatched authz bugs remain reachable |
| Silent breaking changes | Clients bypass via undocumented alternate endpoints |
| No traffic telemetry per version | Zombie versions go unnoticed |
| Inconsistent auth across versions | Attackers choose the weaker version |
API versioning checklist
- Document the versioning strategy and what counts as a breaking change.
- Instrument per-version traffic, errors, and auth failures.
- Apply security fixes to all supported versions—or retire vulnerable ones faster.
- Publish deprecation timelines and enforce them.
- Keep inventory of every live version in the API catalog.
- Ensure new tenants default to the newest secure version.
- Remove dead version code to eliminate accidental re-exposure.
- Test that retired versions truly return hard failures, not soft redirects to weak paths.
The practical takeaway
API versioning is controlled evolution plus planned retirement. It protects clients from surprise breakage and protects the business from immortal legacy endpoints.
Version deliberately, monitor usage, and delete what you no longer support.
Related security terms
API Deprecation
The controlled retirement process that follows versioning decisions.
Zombie API
Forgotten versions that remain reachable without ownership.
OpenAPI Specification
Contract format commonly versioned alongside APIs.
REST API
HTTP API style where versioning strategies are frequently debated.
Improper API Inventory Management
Risk amplified when old versions escape inventory and monitoring.
Frequently asked questions
What is API versioning in simple terms?
It is a way to change an API without instantly breaking every client. You publish a new version, give consumers time to move, then retire the old one.
When do I need a new version?
When a change is incompatible for clients—removed fields, altered meanings, stricter auth, or different error semantics that existing integrations cannot tolerate.
Is URI versioning (/v1) best?
It is popular and visible. Header or media-type versioning can also work. Consistency and clear deprecation policy matter more than the exact mechanism.
Should additive changes require a new version?
Usually no. Backward-compatible additions can stay in the current version if clients ignore unknown fields safely.
How is versioning a security issue?
Old versions often miss patches, keep weak auth, or expose retired data models. Untracked versions become zombie attack surface.
How many versions should stay live?
As few as practical—often N and N-1—with dates, telemetry, and forced retirement.
Do GraphQL APIs version the same way?
GraphQL often evolves by additive schema changes, but breaking removals still need coordinated deprecation and client migration.
References
Explore authoritative guidance and frameworks related to api versioning.
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.