Centralize API base path and introduce /api/v1 versioning

tomvothecoder · tomvothecoder · commit 5a1ae27d0e72 · 2026-01-02T17:54:39.000-08:00
diff --git a/.envs/dev/backend.env.example b/.envs/dev/backend.env.example
@@ -51,7 +51,7 @@ GITHUB_CLIENT_SECRET=your_github_oauth_app_client_secret
 
 # Must match the callback URL in your GitHub App configuration
 # This is the backend OAuth callback endpoint that GitHub calls with the authorization code.
-GITHUB_REDIRECT_URL=https://127.0.0.1/auth/github/callback
+GITHUB_REDIRECT_URL=https://127.0.0.1/api/v1/auth/github/callback
 
 # Secret used to sign OAuth "state" parameter (prevents CSRF)
 # Generate securely with:
diff --git a/.envs/dev/frontend.env.example b/.envs/dev/frontend.env.example
@@ -4,4 +4,4 @@
 
 # Backend configuration
 # -------------------------------------------------------------------
-VITE_API_BASE_URL=https://127.0.0.1:8000/api
+VITE_API_BASE_URL=https://127.0.0.1:8000/api/v1
diff --git a/.envs/dev_docker/backend.env.example b/.envs/dev_docker/backend.env.example
@@ -51,7 +51,7 @@ GITHUB_CLIENT_SECRET=your_github_oauth_app_client_secret
 
 # Must match the callback URL in your GitHub App configuration
 # This is the backend OAuth callback endpoint that GitHub calls with the authorization code.
-GITHUB_REDIRECT_URL=https://127.0.0.1/auth/github/callback
+GITHUB_REDIRECT_URL=https://127.0.0.1/api/v1/auth/github/callback
 
 # Secret used to sign OAuth "state" parameter (prevents CSRF)
 # Generate securely with:
diff --git a/.envs/dev_docker/frontend.env.example b/.envs/dev_docker/frontend.env.example
@@ -4,4 +4,4 @@
 
 # Backend configuration
 # -------------------------------------------------------------------
-VITE_API_BASE_URL=https://127.0.0.1:8000/api
+VITE_API_BASE_URL=https://127.0.0.1:8000/api/v1
diff --git a/.envs/prod/backend.env.example b/.envs/prod/backend.env.example
@@ -51,9 +51,9 @@ GITHUB_CLIENT_SECRET=your_github_oauth_app_client_secret
 
 # Must match the callback URL in your GitHub App configuration
 # This is the backend OAuth callback endpoint that GitHub calls with the authorization code.
-GITHUB_REDIRECT_URL=https://127.0.0.1/auth/github/callback
+GITHUB_REDIRECT_URL=https://127.0.0.1/api/v1/auth/github/callback
 # For production, this must also point to the backend's OAuth callback endpoint
-# GITHUB_REDIRECT_URL=https://app.${DOMAIN}/auth/callback
+# GITHUB_REDIRECT_URL=https://app.${DOMAIN}/api/v1/auth/callback
 
 # Secret used to sign OAuth "state" parameter (prevents CSRF)
 # Generate securely with:
diff --git a/.envs/prod/frontend.env.example b/.envs/prod/frontend.env.example
@@ -4,4 +4,4 @@
 
 # Backend configuration
 # -------------------------------------------------------------------
-VITE_API_BASE_URL=https://127.0.0.1:8000/api
+VITE_API_BASE_URL=https://127.0.0.1:8000/api/v1
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -60,7 +60,7 @@ jobs:
       # --------------------------------------------------
       GITHUB_CLIENT_ID: dummy
       GITHUB_CLIENT_SECRET: dummy
-      GITHUB_REDIRECT_URL: http://localhost/api/auth/github/callback
+      GITHUB_REDIRECT_URL: http://localhost/api/v1/auth/github/callback
       GITHUB_STATE_SECRET_KEY: dummy
 
       # --------------------------------------------------
diff --git a/backend/app/api/constants.py b/backend/app/api/constants.py
@@ -0,0 +1,4 @@
+API_PREFIX = "/api"
+API_VERSION = "v1"
+
+API_BASE = f"{API_PREFIX}/{API_VERSION}"
diff --git a/backend/app/main.py b/backend/app/main.py
@@ -1,6 +1,7 @@
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
+from app.api.constants import API_BASE
 from app.core.config import settings
 from app.core.exceptions import register_exception_handlers
 from app.core.logger import _setup_root_logger
@@ -28,10 +29,10 @@ def create_app() -> FastAPI:
     )
 
     # Register routers.
-    app.include_router(simulations_router, prefix="/api")
-    app.include_router(machine_router, prefix="/api")
-    app.include_router(user_router, prefix="/api")
-    app.include_router(auth_router, prefix="/api")
+    app.include_router(simulations_router, prefix=API_BASE)
+    app.include_router(machine_router, prefix=API_BASE)
+    app.include_router(user_router, prefix=API_BASE)
+    app.include_router(auth_router, prefix=API_BASE)
 
     @app.get("/health")
     async def health():
diff --git a/backend/tests/features/machine/test_api.py b/backend/tests/features/machine/test_api.py
@@ -3,6 +3,7 @@
 from fastapi import HTTPException
 from sqlalchemy.orm import Session
 
+from app.api.constants import API_BASE
 from app.features.machine.api import create_machine, get_machine, list_machines
 from app.features.machine.models import Machine
 from app.features.machine.schemas import MachineCreate
@@ -19,7 +20,7 @@ def test_function_succeeds_with_valid_payload(self, db: Session):
             "notes": "Test machine",
         }
 
-        machine_create = MachineCreate(**payload)
+        machine_create = MachineCreate(**payload)  # type: ignore[arg-type]
         machine = create_machine(machine_create, db)
 
         for key in payload:
@@ -35,7 +36,7 @@ def test_endpoint_succeeds_with_valid_payload(self, client):
             "notes": "Another test machine",
         }
 
-        res = client.post("/api/machines", json=payload)
+        res = client.post(f"{API_BASE}/machines", json=payload)
 
         assert res.status_code == 201
         data = res.json()
@@ -66,7 +67,7 @@ def test_function_raises_error_for_duplicate_name_(self, db: Session):
         }
 
         try:
-            machine_create = MachineCreate(**payload)
+            machine_create = MachineCreate(**payload)  # type: ignore[arg-type]
             create_machine(machine_create, db)
         except HTTPException as e:
             assert str(e) == "400: Machine with this name already exists"
@@ -93,7 +94,7 @@ def test_endpoint_raises_400_for_duplicate_name(self, client, db: Session):
             "notes": "Duplicate machine",
         }
 
-        res = client.post("/api/machines", json=payload)
+        res = client.post(f"{API_BASE}/machines", json=payload)
         assert res.status_code == 400
         assert res.json()["detail"] == "Machine with this name already exists"
 
@@ -128,7 +129,7 @@ def test_endpoint_successfully_list_machines(self, client):
             "chrysalis",
         }
 
-        res = client.get("/api/machines")
+        res = client.get(f"{API_BASE}/machines")
         assert res.status_code == 200
         data = res.json()
 
@@ -167,7 +168,7 @@ def test_endpoint_successfully_get_machine(self, client, db: Session):
         db.commit()
         db.refresh(expected)
 
-        res = client.get(f"/api/machines/{expected.id}")
+        res = client.get(f"{API_BASE}/machines/{expected.id}")
         assert res.status_code == 200
 
         result_endpoint = res.json()
@@ -185,6 +186,6 @@ def test_function_raises_error_if_machine_not_found(self, db: Session):
     def test_endpoint_raises_404_if_machine_not_found(self, client):
         random_id = uuid4()
 
-        res = client.get(f"/api/machines/{random_id}")
+        res = client.get(f"{API_BASE}/machines/{random_id}")
         assert res.status_code == 404
         assert res.json()["detail"] == "Machine not found"
diff --git a/backend/tests/features/simulation/test_api.py b/backend/tests/features/simulation/test_api.py
@@ -3,6 +3,7 @@
 import pytest
 from sqlalchemy.orm import Session
 
+from app.api.constants import API_BASE
 from app.features.machine.models import Machine
 from app.features.simulation.models import Simulation
 from app.features.user.manager import current_active_user
@@ -66,7 +67,7 @@ def test_endpoint_succeeds_with_valid_payload(
             ],
         }
 
-        res = client.post("/api/simulations", json=payload)
+        res = client.post(f"{API_BASE}/simulations", json=payload)
         assert res.status_code == 201
         data = res.json()
         assert data["name"] == payload["name"]
@@ -78,7 +79,7 @@ def test_endpoint_succeeds_with_valid_payload(
 
 class TestListSimulations:
     def test_endpoint_returns_empty_list(self, client):
-        res = client.get("/api/simulations")
+        res = client.get(f"{API_BASE}/simulations")
         assert res.status_code == 200
         assert res.json() == []
 
@@ -109,7 +110,7 @@ def test_endpoint_returns_simulations_with_data(
         db.commit()
         db.refresh(sim)
 
-        res = client.get("/api/simulations")
+        res = client.get(f"{API_BASE}/simulations")
         assert res.status_code == 200
         data = res.json()
         assert len(data) == 1
@@ -131,7 +132,7 @@ def test_endpoint_succeeds_with_valid_id(
             initialization_type="startup",
             simulation_type="control",
             status="created",
-            machine_id=machine.id,
+            machine_id=machine.id,  # type: ignore[union-attr]
             simulation_start_date="2023-01-01T00:00:00Z",
             git_tag="v1.0",
             git_commit_hash="abc123",
@@ -142,11 +143,11 @@ def test_endpoint_succeeds_with_valid_id(
         db.commit()
         db.refresh(sim)
 
-        res = client.get(f"/api/simulations/{sim.id}")
+        res = client.get(f"{API_BASE}/simulations/{sim.id}")
         assert res.status_code == 200
         assert res.json()["name"] == sim.name
 
     def test_endpoint_raises_404_if_simulation_not_found(self, client):
-        res = client.get(f"/api/simulations/{uuid4()}")
+        res = client.get(f"{API_BASE}/simulations/{uuid4()}")
         assert res.status_code == 404
         assert res.json() == {"detail": "Simulation not found"}
diff --git a/backend/tests/features/user/test_api.py b/backend/tests/features/user/test_api.py
@@ -7,6 +7,7 @@
 from fastapi.routing import APIRoute
 from httpx import AsyncClient
 
+from app.api.constants import API_BASE
 from app.core.config import settings
 from app.features.user import oauth
 from app.features.user.models import UserRole
@@ -42,7 +43,7 @@ async def test_github_oauth_authorize_redirect(
         self, async_client: AsyncClient
     ) -> None:
         """Ensure the GitHub OAuth authorize endpoint redirects or renders."""
-        response = await async_client.get("/api/auth/github/authorize")
+        response = await async_client.get(f"{API_BASE}/auth/github/authorize")
 
         assert response.status_code in (
             status.HTTP_200_OK,
@@ -68,7 +69,7 @@ async def test_github_oauth_callback_invalid_state(
             ),
         ):
             response = await async_client.get(
-                "/api/auth/github/callback?code=fake&state=fake"
+                f"{API_BASE}/auth/github/callback?code=fake&state=fake"
             )
 
         # Depending on cookie/JWT config, FastAPI-Users may redirect or just 400
@@ -84,7 +85,7 @@ async def test_logout_clears_cookie(self, async_client: AsyncClient) -> None:
         cookie_name = settings.cookie_name
         async_client.cookies.set(cookie_name, "fake_cookie_value")
 
-        response = await async_client.post("/api/auth/logout")
+        response = await async_client.post(f"{API_BASE}/auth/logout")
 
         assert response.status_code == status.HTTP_200_OK
         assert response.json() == {"message": "Successfully logged out"}
@@ -111,7 +112,7 @@ async def test_logout_clears_cookie(self, async_client: AsyncClient) -> None:
     @pytest.mark.asyncio
     async def test_logout_without_cookie(self, async_client: AsyncClient) -> None:
         """Ensure the logout endpoint works even if no cookie is set."""
-        response = await async_client.post("/api/auth/logout")
+        response = await async_client.post(f"{API_BASE}/auth/logout")
 
         assert response.status_code == status.HTTP_200_OK
         assert response.json() == {"message": "Successfully logged out"}
@@ -122,7 +123,7 @@ class TestUserRoutes:
 
     async def test_users_me_requires_auth(self, async_client: AsyncClient) -> None:
         """Unauthenticated request to /users/me should return 401."""
-        response = await async_client.get("/api/users/me")
+        response = await async_client.get(f"{API_BASE}/users/me")
 
         assert response.status_code == status.HTTP_401_UNAUTHORIZED
 
@@ -141,9 +142,9 @@ def override_user():
                 "role": UserRole.USER.value,
             }
 
-        override_dependency("/api/users/me", "current_user", override_user)
+        override_dependency(f"{API_BASE}/users/me", "current_user", override_user)
 
-        response = await async_client.get("/api/users/me")
+        response = await async_client.get(f"{API_BASE}/users/me")
         assert response.status_code == 200, response.text
 
         data = response.json()
diff --git a/frontend/src/api/api.ts b/frontend/src/api/api.ts
@@ -2,7 +2,7 @@ import axios from 'axios';
 
 import { getAuthenticated } from '@/api/authState';
 
-const API_BASE_URL = import.meta.env.VITE_API_BASE_URL ?? 'https://127.0.0.1:8000/api';
+const API_BASE_URL = import.meta.env.VITE_API_BASE_URL ?? 'https://127.0.0.1:8000/api/v1';
 
 export type LogoutFn = (opts?: { silent?: boolean }) => void;
 let onLogout: LogoutFn | null = null;
