versioning-apis

# 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 l...