API version deprecation audit

Run the API version deprecation audit check

What middleBrick covers

  • Detect deprecated API paths and version identifiers
  • Map findings to OWASP API Top 10 controls
  • Parse OpenAPI 3.0, 3.1, and Swagger 2.0
  • Support authenticated scans with header allowlist
  • Provide diff detection across scheduled scans
  • Export reports for compliance evidence

What is an API version deprecation audit

An API version deprecation audit inventories all published versions of your endpoints, identifies which versions remain in use, and validates that deprecation policies are enforced. The audit maps each route and parameter to a version identifier, checks for deprecated paths still reachable, and confirms that sunset timelines are communicated to consumers.

What teams get wrong when skipping this audit

Without an audit, teams continue serving traffic to deprecated paths, which increases maintenance burden and the attack surface. Breaking changes can be introduced unintentionally, causing client failures in production. Hidden legacy endpoints may retain outdated security configurations, exposing data or functionality that no longer aligns with current policies.

A good deprecation workflow

A robust workflow starts with an inventory of all API versions, typically by reading the OpenAPI specifications for each service. Deprecated operations are marked with a deprecation flag and a sunset date. Communication to consumers is issued via developer portals, changelogs, and email. After a grace period, deprecated versions are removed, and the audit is repeated to verify removal and confirm no unintended regressions.

Example of marking deprecation in OpenAPI:

paths:
  /v1/users:
    get:
      deprecated: true
      description: Deprecated on 2024-01-01. Use /v2/users.
      x-deprecation-sunset: 2024-07-01

Coverage provided by middleBrick

middleBrick scans your public API surface to detect exposed version identifiers in paths and parameters. It maps findings to OWASP API Top 10 controls relevant to change management and helps you prepare for audit evidence around deprecation policies. The scanner supports OpenAPI 3.0, 3.1, and Swagger 2.0, resolving recursive $ref to compare declared versions against runtime behavior.

Key checks include:

  • Identification of deprecated endpoints still returning successful responses
  • Verification that versioning schemes are consistent across the API surface
  • Detection of missing pagination on list endpoints that may retain legacy query patterns
  • Cross-reference of spec definitions to highlight undefined security schemes on deprecated operations

Integration into your lifecycle

Run middleBrick during design reviews to validate versioning strategy before public release. Integrate the scanner into CI/CD pipelines to fail the build when deprecated paths are added without proper flags and sunset dates. Schedule recurring scans to catch regressions introduced by refactoring or emergency fixes, and use the dashboard to track the deprecation status of each API over time.

Run this check on your API See all use cases

Frequently Asked Questions

Can this replace a manual deprecation review?
It reduces manual effort by automating detection of deprecated endpoints, but it does not replace human review for business logic and communication planning.
Does it test that deprecated endpoints are non-functional?
The scanner checks whether deprecated endpoints are reachable and returns responses. It does not perform intrusive payload testing.
How does it handle internal or private APIs?
Authenticated scanning can be used for internal APIs with credentials, provided domain verification is completed. Only read-only methods are exercised.
Can it validate deprecation headers and documentation links?
It detects the presence and format of deprecation markers in specs and runtime responses. Verification of external documentation links requires manual checks.