feat(gateway): X-API-Deprecated header for legacy /api/* paths (Stage 1 PR5)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

backend/app/gateway/app.py

@@ -10,6 +10,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from app.gateway.auth_middleware import AuthMiddleware
 from app.gateway.config import get_gateway_config
 from app.gateway.csrf_middleware import CSRFMiddleware
+from app.gateway.deprecation_middleware import ApiDeprecationMiddleware
 from app.gateway.deps import langgraph_runtime
 from app.gateway.routers import (
     agents,
@@ -356,6 +357,9 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
     # CSRF: Double Submit Cookie pattern for state-changing requests
     app.add_middleware(CSRFMiddleware)
 
+    # Deprecation: stamp X-API-Deprecated on unversioned /api/* responses
+    app.add_middleware(ApiDeprecationMiddleware)
+
     # CORS: when GATEWAY_CORS_ORIGINS is set (dev without nginx), add CORS middleware.
     # In production, nginx handles CORS and no middleware is needed.
     cors_origins_env = os.environ.get("GATEWAY_CORS_ORIGINS", "")

backend/app/gateway/deprecation_middleware.py

@@ -0,0 +1,31 @@
+"""Marks responses to legacy unversioned /api/* paths as deprecated.
+
+Stamps ``X-API-Deprecated: <sunset-date>`` on any /api/* response that is
+neither versioned (/api/v1/*) nor the LangGraph SDK surface
+(/api/langgraph/*). Sunset date is the track-2 contract (2027-01-01).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.types import ASGIApp
+
+API_SUNSET_DATE = "2027-01-01"
+
+
+def _is_deprecated_path(path: str) -> bool:
+    return path.startswith("/api/") and not path.startswith("/api/v1/") and not path.startswith("/api/langgraph/")
+
+
+class ApiDeprecationMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app: ASGIApp) -> None:
+        super().__init__(app)
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        response = await call_next(request)
+        if _is_deprecated_path(request.url.path):
+            response.headers["X-API-Deprecated"] = API_SUNSET_DATE
+        return response

backend/tests/test_api_deprecation_header.py

@@ -0,0 +1,46 @@
+"""Deprecation header tests (Stage 1 PR5)."""
+
+from __future__ import annotations
+
+from starlette.testclient import TestClient
+
+
+def _make_app():
+    from fastapi import FastAPI
+
+    from app.gateway.deprecation_middleware import ApiDeprecationMiddleware
+
+    app = FastAPI()
+    app.add_middleware(ApiDeprecationMiddleware)
+
+    @app.get("/api/threads")
+    async def legacy():
+        return {"ok": True}
+
+    @app.get("/api/v1/threads")
+    async def versioned():
+        return {"ok": True}
+
+    @app.get("/api/langgraph/info")
+    async def lg():
+        return {"ok": True}
+
+    return app
+
+
+def test_legacy_path_gets_deprecation_header():
+    client = TestClient(_make_app())
+    r = client.get("/api/threads")
+    assert r.headers.get("X-API-Deprecated") == "2027-01-01"
+
+
+def test_versioned_path_no_header():
+    client = TestClient(_make_app())
+    r = client.get("/api/v1/threads")
+    assert "X-API-Deprecated" not in r.headers
+
+
+def test_langgraph_path_no_header():
+    client = TestClient(_make_app())
+    r = client.get("/api/langgraph/info")
+    assert "X-API-Deprecated" not in r.headers