# [FEAT] Implement Extensible URI/Header API Versioning Architecture with Strategy-Pattern Routing #92

Labels: enhancement, architecture, api, typescript
Difficulty: High
Module: src/api/

🧠 Concept

Architect and deploy an enterprise-grade API versioning infrastructure across the backend routing layer (src/api/). The implementation must support concurrent multi-version execution through dual-resolution strategies (URL path prefixing and explicit HTTP headers) while decoupling version dispatching from core controller domain logic.

⚠️ Problem

Unversioned API endpoints create tight coupling between client integrations and server-side data models:

1. Breaking Changes Block Deployment: Field deprecations, type shifts, or schema modifications require synchronized updates across all consuming clients.
2. Monolithic Route Drift: Without explicit API version contracts, endpoint handlers accumulate legacy conditional logic (if (req.query.v2) ...), making maintenance error-prone and increasing technical debt.
3. Incomplete OpenAPI Specifications: Lacking structured version metadata leads to inaccurate public documentation, breaking SDK generators and API gateways.

📁 Implementation Scope

• src/api/v1/
• src/api/v2/
• src/api/common/middleware/versionResolver.ts
• src/api/common/strategies/
• docs/openapi/

🛠️ Requirements

1. Dual Version Resolution Strategy

Implement a unified version resolver middleware (versionResolver.ts) using the Strategy Pattern to determine target versions in order of precedence:

1. URI Path Route Strategy: e.g., /api/v1/resources or /api/v2/resources
2. Custom HTTP Header Strategy: e.g., X-API-Version: 2 or Accept: application/vnd.company.v2+json
3. Fallback Strategy: Gracefully fall back to the global active default version (V1) if unassigned.

2. Route Factory & Controller Scaffolding

• Abstract versioned routing logic into reusable route factories (createVersionedRouter()).
• Isolate v1 legacy controllers from v2 controllers, ensuring strict separation of response DTOs and data transformations.
• Implement a central Deprecation Manager that injects standardized HTTP headers (Deprecation: true, Sunset: Sun, 31 Dec 2028 23:59:59 GMT, Link: <...>; rel="successor-version") on flagged legacy routes.

3. Automated Documentation & Schema Generation

• Modularize OpenAPI/Swagger spec generation per version scope (/docs/v1/swagger.json, /docs/v2/swagger.json).
• Expose interactive Swagger UI instances scoped to specific API versions (/docs/v1, /docs/v2).

🎯 Acceptance Criteria

• Dual Resolution: Routes resolve target handlers accurately via both URI path parameters and HTTP headers (X-API-Version).
• Backward Compatibility: All existing endpoints default to /v1/ execution context without breaking current integration tests.
• Deprecation Enforcement: Legacy routes issue RFC 8594-compliant Deprecation and Sunset HTTP response headers.
• OpenAPI Specs: Independent OpenAPI 3.0 documentation generated dynamically for each active version context.
• Unit & Integration Coverage: Integration test suite verifies version mismatch fallback behaviors and invalid version handling (returns 406 Not Acceptable or 400 Bad Request).