Direct answer
Retire an API version only after identifying its consumers, sensitive operations and security differences. An older route can remain reachable even when the newest client no longer uses it.
Inventory the version and clients
List published and observed versioned routes, owners, environments and known consumers. Compare API specifications, gateway configuration and access logs over a representative period, including mobile and partner integrations. A quiet recent log does not prove a client has disappeared.
Reference: OWASP API Security Top 10: Improper Inventory Management.
Compare security boundaries
For each sensitive operation, compare authentication, object authorization, validation, rate controls and logging between versions. Use dedicated test accounts and owned data; a new version's correct restriction does not prove that the legacy endpoint enforces the same policy.
- Include export, bulk, admin and background operations.
- Record routes omitted from the published specification.
- Identify third-party owners before changing shared integrations.
Plan deprecation with consumers
Publish a supported migration path, contact identified owners, set a measured retirement date and track exceptions. Introduce safe observability for remaining traffic without logging credentials or sensitive bodies. Define the response clients receive after shutdown.
Verify shutdown and recovery
In an agreed test environment, disable the retired route and verify it is unavailable through direct origin, proxy and alternate host paths. Confirm the supported version still functions and preserve an approved rollback plan. Monitor for missed clients after release.
Assessment limits
Traffic logs and documentation can miss dormant, offline or externally managed clients. Retirement decisions require coordination with owners and contractual obligations, not an automated route count.
Frequently asked questions
Is an undocumented API automatically unused?
No. Legacy clients, internal services or partners may still rely on it. Correlate documentation with configuration, telemetry and owner confirmation.
Does removing a route from the gateway close every path?
Not necessarily. Verify origin exposure, alternate hosts and deployment environments within the authorized scope.
Primary sources and further reading
These guides combine published security guidance with practical assessment planning. Adapt checks to the owner's policy, environment, and authorized scope.
This guide was prepared with AI assistance using the linked sources and illustrative examples. Check current vendor guidance and your environment before making changes.