Versioning APIs

Overview

Implement API versioning strategies -- URL path (/v1/, /v2/), header-based (Accept: application/vnd.api.v2+json), or query parameter (?version=2) -- with backward compatibility layers, deprecation notices, and automated migration paths. Manage concurrent version support, sunset timelines, and breaking change detection across the API surface.

Prerequisites

• Existing API codebase with route definitions and controller implementations
• Version control history for tracking breaking changes across releases
• OpenAPI specs for each supported API version (or ability to generate them)
• API gateway or reverse proxy capable of version-based routing (optional: Kong, AWS API Gateway)
• Consumer notification channel for deprecation announcements (changelog, email, response headers)

Instructions

1. Audit existing endpoints using Grep and Read to identify current versioning approach (if any) and catalog all public-facing endpoints with their request/response contracts.
2. Select a versioning strategy based on API consumer patterns: URL path versioning for public APIs, header versioning for APIs needing clean URLs, or content negotiation for advanced use cases.
3. Create a version router that directs requests to the appropriate version handler set based on the extracted version identifier from URL, header, or query parameter.
4. Implement version-specific controller directories (/v1/controllers/, /v2/controllers/) with shared business logic extracted into version-independent service layers.