Merge pull request #88 from DevanshuNEU/feature/issue-55-api-versioning

feat(api): Add centralized API versioning system (#55)

Author: DevanshuNEU

backend/config/__init__.py

@@ -0,0 +1 @@
+# Backend configuration module

backend/config/api.py

@@ -0,0 +1,52 @@
+"""
+API Configuration - Single Source of Truth for API Versioning
+
+Change API_VERSION here to update all routes across the application.
+Example: "v1" -> "v2" will change /api/v1/* to /api/v2/*
+"""
+
+# =============================================================================
+# API VERSION CONFIGURATION
+# =============================================================================
+
+API_VERSION = "v1"
+
+# =============================================================================
+# DERIVED PREFIXES (auto-calculated from version)
+# =============================================================================
+
+# Current versioned API prefix: /api/v1
+API_PREFIX = f"/api/{API_VERSION}"
+
+# Legacy prefix for backward compatibility: /api
+# Routes here will be deprecated but still functional
+LEGACY_API_PREFIX = "/api"
+
+# =============================================================================
+# DEPRECATION SETTINGS
+# =============================================================================
+
+# When True, legacy routes (/api/*) will include deprecation warning headers
+LEGACY_DEPRECATION_ENABLED = True
+
+# Header to add on deprecated routes
+DEPRECATION_HEADER = "X-API-Deprecated"
+DEPRECATION_MESSAGE = f"This endpoint is deprecated. Please use {API_PREFIX} instead."
+
+# =============================================================================
+# HELPER FUNCTIONS
+# =============================================================================
+
+def get_versioned_prefix() -> str:
+    """Get the current versioned API prefix."""
+    return API_PREFIX
+
+
+def get_legacy_prefix() -> str:
+    """Get the legacy (deprecated) API prefix."""
+    return LEGACY_API_PREFIX
+
+
+def is_legacy_route(path: str) -> bool:
+    """Check if a route path is using the legacy prefix."""
+    return path.startswith(LEGACY_API_PREFIX) and not path.startswith(API_PREFIX)

backend/main.py

@@ -10,6 +10,9 @@
 from starlette.responses import JSONResponse
 import os
 
+# Import API config (single source of truth for versioning)
+from config.api import API_PREFIX, API_VERSION
+
 # Import routers
 from routes.auth import router as auth_router
 from routes.health import router as health_router
@@ -68,17 +71,20 @@ async def dispatch(self, request: Request, call_next):
 
 
 # ===== ROUTERS =====
-
-app.include_router(health_router)
-app.include_router(auth_router)
-app.include_router(playground_router)
-app.include_router(repos_router)
-app.include_router(search_router)
-app.include_router(analysis_router)
-app.include_router(api_keys_router)
-
-# WebSocket endpoint (can't be in router easily)
-app.add_api_websocket_route("/ws/index/{repo_id}", websocket_index)
+# All API routes are prefixed with API_PREFIX (e.g., /api/v1)
+# Route files define their sub-path (e.g., /auth, /repos)
+# Final paths: /api/v1/auth, /api/v1/repos, etc.
+
+app.include_router(health_router)  # /health stays at root (no versioning needed)
+app.include_router(auth_router, prefix=API_PREFIX)
+app.include_router(playground_router, prefix=API_PREFIX)
+app.include_router(repos_router, prefix=API_PREFIX)
+app.include_router(search_router, prefix=API_PREFIX)
+app.include_router(analysis_router, prefix=API_PREFIX)
+app.include_router(api_keys_router, prefix=API_PREFIX)
+
+# WebSocket endpoint (versioned)
+app.add_api_websocket_route(f"{API_PREFIX}/ws/index/{{repo_id}}", websocket_index)
 
 
 # ===== ERROR HANDLERS =====

backend/routes/analysis.py

@@ -9,7 +9,7 @@
 from services.input_validator import InputValidator
 from middleware.auth import require_auth, AuthContext
 
-router = APIRouter(prefix="/api/repos", tags=["Analysis"])
+router = APIRouter(prefix="/repos", tags=["Analysis"])
 
 
 class ImpactRequest(BaseModel):

backend/routes/api_keys.py

@@ -5,7 +5,7 @@
 from dependencies import api_key_manager, rate_limiter, metrics
 from middleware.auth import require_auth, AuthContext
 
-router = APIRouter(prefix="/api", tags=["API Keys"])
+router = APIRouter(prefix="", tags=["API Keys"])
 
 
 class CreateAPIKeyRequest(BaseModel):

backend/routes/auth.py

@@ -9,7 +9,7 @@
 from middleware.auth import get_current_user
 
 # Create router
-router = APIRouter(prefix="/api/auth", tags=["Authentication"])
+router = APIRouter(prefix="/auth", tags=["Authentication"])
 
 
 # Request/Response Models

backend/routes/playground.py

@@ -7,7 +7,7 @@
 from dependencies import indexer, cache, repo_manager
 from services.input_validator import InputValidator
 
-router = APIRouter(prefix="/api/playground", tags=["Playground"])
+router = APIRouter(prefix="/playground", tags=["Playground"])
 
 # Demo repo mapping (populated on startup)
 DEMO_REPO_IDS = {}

backend/routes/repos.py

@@ -13,7 +13,7 @@
 from services.input_validator import InputValidator
 from middleware.auth import require_auth, AuthContext
 
-router = APIRouter(prefix="/api/repos", tags=["Repositories"])
+router = APIRouter(prefix="/repos", tags=["Repositories"])
 
 
 class AddRepoRequest(BaseModel):

backend/routes/search.py

@@ -11,7 +11,7 @@
 from services.input_validator import InputValidator
 from middleware.auth import require_auth, AuthContext
 
-router = APIRouter(prefix="/api", tags=["Search"])
+router = APIRouter(prefix="", tags=["Search"])
 
 
 class SearchRequest(BaseModel):

backend/tests/test_api.py

@@ -4,6 +4,9 @@
 """
 import pytest
 
+# Import API prefix from centralized config (single source of truth)
+from config.api import API_PREFIX
+
 
 class TestAPIAuthentication:
     """Test authentication and authorization"""
@@ -15,20 +18,20 @@ def test_health_check_no_auth_required(self, client_no_auth):
 
     def test_protected_endpoint_requires_auth(self, client_no_auth):
         """Protected endpoints should require API key"""
-        response = client_no_auth.get("/api/repos")
+        response = client_no_auth.get(f"{API_PREFIX}/repos")
         assert response.status_code in [401, 403]  # Either unauthorized or forbidden
 
     def test_valid_dev_key_works(self, client_no_auth, valid_headers):
         """Valid development API key should work in debug mode"""
         # Note: This tests actual auth, requires DEBUG=true and DEV_API_KEY set
-        response = client_no_auth.get("/api/repos", headers=valid_headers)
+        response = client_no_auth.get(f"{API_PREFIX}/repos", headers=valid_headers)
         # May return 200 or 401 depending on env setup during test
         assert response.status_code in [200, 401]
 
     def test_invalid_key_rejected(self, client_no_auth):
         """Invalid API keys should be rejected"""
         response = client_no_auth.get(
-            "/api/repos",
+            f"{API_PREFIX}/repos",
             headers={"Authorization": "Bearer invalid-random-key"}
         )
         assert response.status_code in [401, 403]
@@ -41,7 +44,7 @@ def test_reject_file_scheme_urls(self, client, valid_headers, malicious_payloads
         """Should block file:// URLs"""
         for url in malicious_payloads["file_urls"]:
             response = client.post(
-                "/api/repos",
+                f"{API_PREFIX}/repos",
                 headers=valid_headers,
                 json={"name": "test", "git_url": url}
             )
@@ -52,7 +55,7 @@ def test_reject_localhost_urls(self, client, valid_headers, malicious_payloads):
         """Should block localhost/private IP URLs"""
         for url in malicious_payloads["localhost_urls"]:
             response = client.post(
-                "/api/repos",
+                f"{API_PREFIX}/repos",
                 headers=valid_headers,
                 json={"name": "test", "git_url": url}
             )
@@ -65,7 +68,7 @@ def test_reject_invalid_repo_names(self, client, valid_headers):
 
         for name in invalid_names:
             response = client.post(
-                "/api/repos",
+                f"{API_PREFIX}/repos",
                 headers=valid_headers,
                 json={"name": name, "git_url": "https://github.com/test/repo"}
             )
@@ -79,7 +82,7 @@ def test_reject_sql_injection_attempts(self, client, valid_headers, malicious_pa
         """Should block SQL injection in search queries"""
         for sql_query in malicious_payloads["sql_injection"]:
             response = client.post(
-                "/api/search",
+                f"{API_PREFIX}/search",
                 headers=valid_headers,
                 json={"query": sql_query, "repo_id": "test-id"}
             )
@@ -90,7 +93,7 @@ def test_reject_sql_injection_attempts(self, client, valid_headers, malicious_pa
     def test_reject_empty_queries(self, client, valid_headers):
         """Should reject empty search queries"""
         response = client.post(
-            "/api/search",
+            f"{API_PREFIX}/search",
             headers=valid_headers,
             json={"query": "", "repo_id": "test-id"}
         )
@@ -100,7 +103,7 @@ def test_reject_empty_queries(self, client, valid_headers):
     def test_reject_oversized_queries(self, client, valid_headers):
         """Should reject queries over max length"""
         response = client.post(
-            "/api/search",
+            f"{API_PREFIX}/search",
             headers=valid_headers,
             json={"query": "a" * 1000, "repo_id": "test-id"}
         )
@@ -115,7 +118,7 @@ def test_reject_path_traversal_attempts(self, client, valid_headers, malicious_p
         """Should block path traversal in impact analysis"""
         for path in malicious_payloads["path_traversal"]:
             response = client.post(
-                "/api/repos/test-id/impact",
+                f"{API_PREFIX}/repos/test-id/impact",
                 headers=valid_headers,
                 json={"repo_id": "test-id", "file_path": path}
             )
@@ -141,7 +144,7 @@ def test_max_limits_configured(self):
     def test_search_results_capped(self, client, valid_headers):
         """Search results should be capped at maximum"""
         response = client.post(
-            "/api/search",
+            f"{API_PREFIX}/search",
             headers=valid_headers,
             json={
                 "query": "test query",