API Security API Versioning and Deprecation Managing

APIs do not exist in a static moment. They evolve, get updated, accumulate versions, and eventually need to be retired. Every active API version is an attack surface. Managing versions with a security-first mindset reduces that surface over time and ensures that security improvements benefit all users — not just those using the newest version.

Why Versioning Creates Security Risk

Each API version is a separate attack surface:

v1 deployed in 2020 → No rate limiting, weaker auth
v2 deployed in 2022 → Rate limiting added, JWT upgraded
v3 deployed in 2024 → BOLA fixes, field-level auth, strict schema

If all three versions run simultaneously:
  Attackers specifically target v1 for its weaker controls.
  Security improvements in v3 provide no protection to v1 users.
  Development team must maintain and patch three code bases.

Goal: Minimize the number of active versions.
      Retire old versions on a defined, enforced schedule.

Types of API Versioning

Method 1: URL Path Versioning (Most Common)
  https://api.company.com/v1/users
  https://api.company.com/v2/users
  
  Pros: Clear, explicit, easy to see in logs.
  Cons: Version in URL; changing version changes all client URLs.
  Security advantage: Easy to monitor per-version traffic.
                      Easy to enforce different rate limits per version.

Method 2: Header Versioning
  GET /api/users
  API-Version: 2
  
  Pros: URL does not change; cleaner REST design.
  Cons: Harder to monitor in gateway logs; requires header inspection.
  
Method 3: Query Parameter Versioning
  GET /api/users?version=2
  
  Pros: Easy to test in browser.
  Cons: Version in URL (appears in logs), easy to miss or forget.

Method 4: Accept Header (Media Type)
  Accept: application/vnd.company.api+json; version=2
  
  Pros: True REST content negotiation.
  Cons: Complex to implement and test; harder to monitor.

Recommendation for security visibility: URL path versioning.
  Logs clearly show which version is being called.
  Gateway policies easily applied per version prefix.

Semantic Versioning for APIs

API changes fall into three categories with different security implications:

Patch (v1.0 → v1.0.1): Bug fixes, security patches, no breaking changes.
  Example: Fix a BOLA vulnerability in /api/orders without changing the
           request/response format.
  Security rule: Deploy patch versions IMMEDIATELY.
                 Do not wait for client migration. Bug fixes are critical.

Minor (v1.0 → v1.1): New features added, backwards compatible.
  Example: Add a new optional field to responses, add a new endpoint.
  Security rule: New security headers, improved error handling.
                 Old clients continue working without modification.

Major (v1 → v2): Breaking changes, clients must update.
  Example: Authentication method changed, response format restructured.
  Security rule: This is where significant security improvements live.
                 Define a migration window: 6-12 months for clients to move.
                 Run both versions in parallel during transition.
                 Set a hard shutdown date for v1.

The Deprecation Process

A structured deprecation process gives clients time to migrate
while ensuring old, insecure versions do not run indefinitely.

Phase 1: Announcement (12 months before shutdown)
  Announce deprecation of v1 in:
  - API documentation
  - Developer newsletters
  - API changelog
  - Developer dashboard / portal notifications
  
  Set a firm sunset date: "v1 will be shut down on January 1, 2026."

Phase 2: Response Headers (starting immediately)
  Every response from deprecated version includes:
  
  Deprecation: true
  Sunset: Tue, 01 Jan 2026 00:00:00 GMT
  Link: <https://api.company.com/v2/migration-guide>; rel="successor-version"
  
  Well-implemented client libraries automatically detect and log these headers.
  Developers see warnings in their own logs.

Phase 3: Monitoring and Outreach
  Track which clients still use v1 (API key analytics).
  Contact high-usage clients directly.
  Offer migration support, documentation, code examples.

Phase 4: Soft Shutdown
  3 months before sunset: rate limit v1 more aggressively.
  1 month before sunset: v1 returns 503 for 1 hour per day ("brownouts").
  This forces remaining clients to test their migration.

Phase 5: Hard Shutdown
  Sunset date arrives.
  v1 returns 410 Gone with a message pointing to v2.
  HTTP 410 is the correct status code for permanently removed resources.

Backporting Security Fixes

During the deprecation window, security vulnerabilities found in v1
MUST be patched in v1 — even though v1 is deprecated.

Scenario:
  BOLA vulnerability discovered affecting /api/v1/orders/{id}.
  v2 already fixed this with ownership checks.
  v1 has 2 months until shutdown.

Incorrect response: "v1 is deprecated. Users should migrate to v2."
Correct response:   Patch the BOLA in v1 immediately.
                    Publish a security advisory.
                    Announce in deprecation communications.

If v1 is not patched:
  Every user still on v1 is vulnerable for 2 months.
  Company is liable for breach during this period.
  Trust in the developer ecosystem is damaged.

Rule: Deprecation does not reduce security responsibility.
      All active versions must receive security patches.

API Inventory and Discovery

Before you can manage versions, you must know what exists.

API Inventory Problem:
  Large organizations often have hundreds of APIs.
  Many were built by teams that have since left.
  Some are undocumented and known only to original developers.
  Shadow APIs (unknown, unregistered) are the most dangerous.

API Discovery Methods:

  1. API Gateway Inventory:
     Every API behind a gateway is registered.
     Gateway provides a definitive list.
     Gaps: APIs not behind the gateway are invisible.

  2. Network Traffic Analysis:
     Inspect network traffic at the perimeter.
     APIs are identified by traffic patterns and endpoints observed.
     Tools: AWS VPC Flow Logs, network taps, service mesh telemetry.

  3. Code Repository Scanning:
     Scan source code repositories for API definitions.
     OpenAPI specs, route definitions, API client calls.
     Tools: GitHub code search, custom scanners.

  4. External Attack Surface Scanning:
     Tools like Shodan, Censys, or custom DNS enumeration
     discover publicly accessible APIs you might not know about.
     Run this against your own organization regularly.

API Inventory Contents (Minimum):
  - API name and description
  - Owner team and contact
  - All active versions and their URLs
  - Authentication method
  - Data classification (public, internal, sensitive, regulated)
  - Last security review date
  - Deprecation status and sunset date

Security Review as Part of API Lifecycle

Security should be validated at every major lifecycle event:

Design Phase:
  Threat modeling: what can go wrong with this API design?
  Security requirements defined before development begins.
  OpenAPI spec reviewed for security completeness.

Development Phase:
  Developer security training for the specific API type.
  Static analysis (SAST) tools run in CI/CD pipeline.
  Peer code review with security checklist.

Pre-Release Phase:
  Dynamic security testing (DAST) against staging environment.
  Penetration testing for high-risk APIs.
  Security sign-off required before production deployment.

Production Phase:
  Continuous monitoring and anomaly detection (Topic 23).
  Periodic security re-assessment (annually or after major changes).
  Bug bounty program for public APIs.

Deprecation Phase:
  Security patch responsibility clearly assigned until shutdown.
  Final security review of data migration process.
  Verify all sensitive data removed from deprecated version infrastructure.

Changelog and Security Communication

Every API release should have a published changelog.
Security-relevant changes must be clearly marked.

Example API Changelog Entry:

## API v2.3.0 — Released March 15, 2025

### Security Fixes (Action Required)
- [CVE-2025-1234] Fixed Broken Object Level Authorization in
  GET /api/v2/invoices/{id}. Users could previously access other
  users' invoices. Patched to enforce ownership validation.
  SEVERITY: HIGH — Upgrade recommended immediately.

- Rate limiting applied to POST /api/v2/password-reset.
  Previous: unlimited. Now: 3 requests per hour per email address.
  This prevents automated account takeover attempts.

### New Features
- GET /api/v2/audit-log — New endpoint to view your account's
  access history (authentication required).

### Deprecation Notice
- v1 API endpoints are scheduled for shutdown on January 1, 2026.
  Migration guide: https://docs.company.com/api/v1-to-v2
  Contact: api-support@company.com

Security changelogs should always include:
  CVE ID if applicable.
  Severity rating (Critical/High/Medium/Low).
  Which endpoints are affected.
  What the vulnerability allowed.
  Whether action is required from API consumers.

Key Points

  • Every active API version is an attack surface. Minimize the number of running versions and retire old ones on a firm schedule.
  • URL path versioning provides the best security visibility — version-specific traffic is easily identifiable in logs and gateway policies.
  • Send deprecation headers (Deprecation: true, Sunset:) in every response from deprecated versions so clients detect and act on warnings.
  • Deprecated versions must still receive security patches until their hard shutdown date. Deprecation does not reduce security responsibility.
  • Use brownout periods (deliberate short outages) in the final weeks before shutdown to force remaining clients to complete migration.
  • Maintain an API inventory of all active versions, owners, and security status. Unknown APIs (shadow APIs) cannot be protected.
Previous lessons
Back to courses
Next lessons

Leave a Comment