Implement API versioning with /v1 URL prefix and backward compatibility

[Menjay7]

Description

This PR introduces API versioning using a /v1 URL prefix while maintaining backward compatibility for existing clients. The change establishes a scalable versioning strategy that enables future API evolution without disrupting current integrations.

Motivation

As the API grows, introducing breaking changes becomes increasingly challenging. Versioning provides a structured approach to evolving the API while ensuring existing consumers continue to function without immediate migration requirements.

Changes
Added API versioning support using the /v1 URL prefix.
Introduced version-aware routing and middleware.
Maintained backward compatibility by mapping unversioned routes to v1 endpoints.
Added version detection and default version handling.
Updated API documentation and examples to use versioned endpoints.
API Structure
Current (Backward Compatible)
GET /users
POST /auth/login
GET /products
Versioned Endpoints
GET /v1/users
POST /v1/auth/login
GET /v1/products
Backward Compatibility Behavior
GET /users → GET /v1/users
POST /auth/login → POST /v1/auth/login
GET /products → GET /v1/products
Implementation Details
Introduced API_VERSIONS, DEFAULT_VERSION, and LATEST_VERSION constants.
Added version detection middleware for incoming requests.
Created version-specific route modules (routes/v1, routes/v2, etc.).
Established a routing pattern that supports future versions without restructuring existing APIs.
Ensured unversioned requests default to v1.
Benefits
Enables safe introduction of breaking changes in future releases.
Preserves compatibility for existing API consumers.
Simplifies maintenance of multiple API versions.
Provides a clear and predictable API evolution strategy.
Establishes a foundation for deprecation and migration workflows.
Testing
Verified /v1 endpoints function correctly.
Verified unversioned routes resolve to v1.
Tested version detection middleware and default version behavior.
Confirmed existing client integrations remain unaffected.
Updated API documentation and integration tests.
Obtain team review and approval.
Future Considerations
Add support for additional API versions (/v2, /v3, etc.).
Introduce API deprecation headers and migration notices.
Add metrics and logging for version adoption tracking.
Consider supporting header-based versioning alongside URL-based versioning for advanced use cases.closed #59

[nanaf6203-bit]

Requesting changes @Menjay7 — CI is red (Secret Scan, Lint, TypeScript Check, Build, and E2E Tests are failing). For #59, please fix against the latest main and re-run; once green we can land the /v1 versioning. Let me know if you want a hand reproducing the failures.