API inventory and versioning: retire old endpoints safely

What belongs in the API inventory

Inventory from your own reliable sources: routing and gateway configuration, deployment definitions, API documentation, service registries and existing usage logs. No single source proves completeness. A forgotten route may exist in code but be absent from documentation; a retired version may still be reachable through a second host.

OWASP identifies incomplete inventories and forgotten versions as a distinct API risk. Include third-party data flows and different environments. OWASP API9:2023.

A small team does not necessarily need a new tool. A maintained mapping could initially look like this:

The values are fictional and unreachable. Your inventory should contain no credential values. References to responsible systems and key identifiers suffice; secrets remain in their designated storage.

Compare documentation with actual operation

OpenAPI describes operations, parameters and responses. This helps compare contracts but disables no route. An operation's deprecated field is also initially a label. OpenAPI 3.2.0: Operation Object.

Compare documented operations with actual routing and approved test cases. Clarify discrepancies specifically: is the undocumented path intentional? Which authentication and permissions apply there? Does an older version receive the same security fixes as the new one?

A version number does not answer these questions. It may identify the API, a document edition or deployed software package. Define which version signal the client actually selects. Several simultaneous selection paths, such as host plus path plus header, increase maintenance effort and must remain consistent.

A change that ‘only adds a field’ may still affect specific clients, such as strict parsers or handling of new state values. Check compatibility against the contract and representative consumers. Semantic version numbers do not replace that check.

Plan migration as a managed period

First name the replacement and required client change. Include differences in permissions, formats, error responses and side effects. An example call to the new route helps little if it is unclear whether an open job concerns the same state across both versions.

Identify affected clients of your own and agreed partners using existing usage data and responsibilities. A short period without observed access does not prove that no further use remains: monthly tasks or paused integrations may return later. Document the observation period and remaining uncertainty.

During migration, the old version remains a real part of the product. Do not automatically give it weaker authentication, missing quantity limits or unmaintained libraries. If it contains a concrete vulnerability, explicitly weigh repair, restriction and earlier shutdown.

Agree a date, responsible people and a rollback path. Extending the transition is a decision with a new date and continued maintenance. It should not silently reopen an abandoned service.

Distinguish Deprecation from Sunset

Deprecation states that a resource is considered obsolete or will be in future. Sunset announces when it is expected no longer to be available as before. Both provide information; technical retirement happens elsewhere.

A self-created example of a planned transition:

Deprecation: @1790812800
Sunset: Thu, 01 Apr 2027 00:00:00 GMT
Link: <https://docs.example.invalid/migration/v2>; rel="deprecation"

Here deprecation begins on 1 October 2026 at 00:00 UTC. The announced sunset is 1 April 2027 at 00:00 UTC. The documentation address is only an example.

Under RFC 9745, Deprecation uses a Structured Field date prefixed with @; Sunset uses an HTTP date. RFC 9745 is a Proposed Standard from March 2025. RFC 8594 describes Sunset as an Informational RFC. When both are used, Sunset must not precede the Deprecation date. RFC 9745, sections 2–5, RFC 8594, sections 3–5.

The information initially applies to the responding resource. If it covers an entire version, document that broader scope clearly. A header at the starting address does not automatically disable every other endpoint. Sunset also does not guarantee availability until exactly that time. Clients should read the migration contract and handle possible outages in any case.

Verify retirement through the actual path

Remove or block the old operation at relevant entry points under the planned contract. Check alternative hosts, gateway routes, direct service paths, former documentation/debug access and background consumers from the inventory. For a deliberately removed endpoint, 410 may be suitable, for example; the appropriate response depends on the contract and remaining operation. No single status is prescribed for every retirement.

Disabling DNS alone is insufficient as general evidence. Another host or direct route may still reach the same application. A 404 at one public URL likewise says nothing about old administration paths.

Provide evidence through the predefined control cases of your own and configuration: the old effect is unreachable, the new route works for authorised test users, open jobs remain resolved, and required safeguards still apply. Record test time, environment and deliberately untested paths. No real retirement was performed for this article.

Rollback needs a narrow scope. If the new version fails business requirements, a tested predecessor may temporarily be necessary. Reactivate neither revoked keys nor the vulnerability that prompted retirement. A single function may need to remain suspended until a safe replacement is available.

Maintain libraries, images and runtimes too

Secure operation covers more than visible API versions. HTTP client, framework, parser, runtime and container base have their own version and maintenance cycles. Record actually delivered versions, including transitive dependencies where your tools reliably identify them, and assign someone to security notices.

Map a notice to the package used, its origin, version and affected function. A version string visible in a header is only a clue. Maintained distributions may backport fixes; conversely, an absent banner does not prove current software.

Plan security updates with targeted tests of affected functions, an approved delivery path and a known rollback option. If a vulnerable function is temporarily disabled, record the measure, remaining work and end date. OWASP explicitly describes these context-dependent approaches as recommendations, not recipes with guaranteed effects. OWASP: Vulnerable Dependency Management.

Maintenance needs a traceable completion

Connect version changes and shutdown with logging and monitoring: who still uses the old path, which errors arise after switching, and who responds? Update the inventory during release rather than reconstructing it at the next incident.

The API Security Check performs neither endpoint inventory nor a complete dependency or CVE audit. A public response finding can provide an individual starting point; inventory, maintenance and retirement require your own configuration and operational evidence. Testing your own API promises helps assemble suitable control cases.

Next steps