Prefix all admin API endpoints with /api/v1/ (open-telemetry#2486)

Adds `/api/v1/` versioning prefix to all admin API endpoints to support
future API evolution without breaking changes.

# Change Summary

All API routes are nested under `/api/v1` in a single place (`lib.rs`)
using Axum's `Router::nest`. UI routes (`/`, `/dashboard`, `/static/*`)
remain at root.

```rust
// Before
let app = Router::new()
    .merge(health::routes())      // /status, /livez, /readyz
    .merge(telemetry::routes())   // /telemetry/metrics, /metrics
    .merge(pipeline_group::routes())
    .merge(pipeline::routes())
    .merge(dashboard::routes());

// After
let api_routes = Router::new()
    .merge(health::routes())      // → /api/v1/status, /api/v1/livez, /api/v1/readyz
    .merge(telemetry::routes())   // → /api/v1/telemetry/metrics, /api/v1/metrics
    .merge(pipeline_group::routes())
    .merge(pipeline::routes());

let app = Router::new()
    .nest("/api/v1", api_routes)
    .merge(dashboard::routes());  // unchanged
```

**UI updated:**
- `metrics-api.js`: endpoint candidates updated to
`/api/v1/telemetry/metrics` and `/api/v1/metrics`
- `polling-controller.js`: health/status fetch paths updated to
`/api/v1/livez`, `/api/v1/readyz`, `/api/v1/status`

**Docs updated:**
- `crates/admin/README.md` and `docs/admin/architecture.md` reflect new
paths

**Validation crate updated:**
- `crates/validation/src/simulate.rs`: `wait_for_ready`,
`fetch_metrics`, and `shutdown_pipeline` now use `/api/v1/readyz`,
`/api/v1/telemetry/metrics`, and `/api/v1/pipeline-groups/shutdown`
respectively

**Pipeline perf test infrastructure updated:**
- All YAML/Jinja2 test suite configs under `tools/pipeline_perf_test/`
updated from `/telemetry/metrics` → `/api/v1/telemetry/metrics` and
`/pipeline-groups/` → `/api/v1/pipeline-groups/` (14 files across
`continuous/`, `nightly/`, and `templates/` directories)

## What issue does this PR close?

## How are these changes tested?

All 9 existing admin unit tests pass. The UI polling logic is covered by
existing JS module tests. The full `cargo xtask check` was run per
AGENTS.md requirements: structure checks ✅, `cargo fmt --all` ✅, `cargo
clippy --workspace --all-targets -- -D warnings` ✅. The
`otap-df-validation` integration tests (`no_processor`,
`debug_processor`, `attribute_processor_pipeline`,
`filter_processor_pipeline`) now pass with the updated endpoint paths.

## Are there any user-facing changes?

Yes. All admin API endpoints now require the `/api/v1/` prefix:

| Old | New |
|-----|-----|
| `/status` | `/api/v1/status` |
| `/livez` | `/api/v1/livez` |
| `/readyz` | `/api/v1/readyz` |
| `/metrics` | `/api/v1/metrics` |
| `/telemetry/metrics` | `/api/v1/telemetry/metrics` |
| `/telemetry/metrics/aggregate` | `/api/v1/telemetry/metrics/aggregate`
|
| `/pipeline-groups/status` | `/api/v1/pipeline-groups/status` |
| `/pipeline-groups/shutdown` | `/api/v1/pipeline-groups/shutdown` |
| `/pipeline-groups/{g}/pipelines/{p}/status` |
`/api/v1/pipeline-groups/{g}/pipelines/{p}/status` |

The embedded UI continues to work as its fetch paths are updated in
lockstep.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: lquerel <657994+lquerel@users.noreply.github.com>
Co-authored-by: Laurent Quérel <l.querel@f5.com>
Co-authored-by: jmacd <3629705+jmacd@users.noreply.github.com>
Co-authored-by: Joshua MacDonald <jmacd@users.noreply.github.com>

Author: 3 people

rust/otap-dataflow/crates/admin/README.md

@@ -20,21 +20,21 @@ For the admin docs landing page, see
 
 ### Telemetry
 
-- `GET /telemetry/live-schema`
-- `GET /telemetry/metrics`
-- `GET /telemetry/metrics/aggregate`
-- `GET /metrics` (alias for `/telemetry/metrics`)
+- `GET /api/v1/telemetry/live-schema`
+- `GET /api/v1/telemetry/metrics`
+- `GET /api/v1/telemetry/metrics/aggregate`
+- `GET /api/v1/metrics` (alias for `/api/v1/telemetry/metrics`)
 
 ### Health and status
 
-- `GET /status`
-- `GET /livez`
-- `GET /readyz`
-- `GET /pipeline-groups/status`
-- `GET /pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}/status`
-- `GET /pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}/livez`
-- `GET /pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}/readyz`
-- `POST /pipeline-groups/shutdown`
+- `GET /api/v1/status`
+- `GET /api/v1/livez`
+- `GET /api/v1/readyz`
+- `GET /api/v1/pipeline-groups/status`
+- `GET /api/v1/pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}/status`
+- `GET /api/v1/pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}/livez`
+- `GET /api/v1/pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}/readyz`
+- `POST /api/v1/pipeline-groups/shutdown`
 
 ## Embedded UI layout (crate-relative)
 
@@ -54,7 +54,7 @@ Assets are embedded in the binary via `include_dir` and served by
 ## Runtime notes
 
 - UI polling cadence is 2 seconds.
-- UI metrics polling uses same-origin `/telemetry/metrics` then `/metrics`.
+- UI metrics polling uses same-origin `/api/v1/telemetry/metrics` then `/api/v1/metrics`.
 - Supported optional query param: `keep_all_zeroes=true|false`.
 
 For operational semantics, metric-name contracts, graph rules, and testing
@@ -89,7 +89,8 @@ guidance, see [`docs/admin/architecture.md`](../../docs/admin/architecture.md).
 - [ ] Protect `POST /pipeline-groups/shutdown` with stricter access controls
   than read-only endpoints.
 - [ ] Apply the same hardened response headers to API endpoints
-  (`/status`, `/livez`, `/readyz`, `/telemetry/*`, `/metrics`), not only UI/static.
+  (`/api/v1/status`, `/api/v1/livez`, `/api/v1/readyz`,
+  `/api/v1/telemetry/*`, `/api/v1/metrics`), not only UI/static.
 - [ ] Harden CSP further by removing `style-src 'unsafe-inline'` (move toward
   nonce/hash-based style policies).
 - [ ] Add rate limiting / throttling to protect admin and telemetry endpoints.
@@ -104,4 +105,4 @@ guidance, see [`docs/admin/architecture.md`](../../docs/admin/architecture.md).
   - strong authentication/authorization
   - network ACLs / source allow-listing
   - route-level restrictions for mutating endpoints such as
-    `/pipeline-groups/shutdown`
+    `/api/v1/pipeline-groups/shutdown`

rust/otap-dataflow/crates/admin/src/health.rs

@@ -3,9 +3,9 @@
 
 //! Global health and status endpoints.
 //!
-//! - GET `/status` - list all pipelines and their status
-//! - GET `/livez` - liveness probe
-//! - GET `/readyz` - readiness probe
+//! - GET `/api/v1/status` - list all pipelines and their status
+//! - GET `/api/v1/livez` - liveness probe
+//! - GET `/api/v1/readyz` - readiness probe
 
 use crate::AppState;
 use axum::extract::State;

rust/otap-dataflow/crates/admin/src/lib.rs

@@ -58,11 +58,14 @@ pub async fn run(
         ctrl_msg_senders: Arc::new(Mutex::new(ctrl_msg_senders)),
     };
 
-    let app = Router::new()
+    let api_routes = Router::new()
         .merge(health::routes())
         .merge(telemetry::routes())
         .merge(pipeline_group::routes())
-        .merge(pipeline::routes())
+        .merge(pipeline::routes());
+
+    let app = Router::new()
+        .nest("/api/v1", api_routes)
         .merge(dashboard::routes())
         .layer(ServiceBuilder::new())
         .with_state(app_state);

rust/otap-dataflow/crates/admin/src/pipeline.rs

@@ -4,11 +4,11 @@
 //! Pipeline endpoints.
 //! Status: Not implemented.
 //!
-//! - GET `/pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}`
+//! - GET `/api/v1/pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}`
 //!   Get the configuration of the specified pipeline.
-//! - GET `/pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}/status`
+//! - GET `/api/v1/pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}/status`
 //!   Get the status of the specified pipeline.
-//! - POST `/pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}/shutdown`
+//! - POST `/api/v1/pipeline-groups/{pipeline_group_id}/pipelines/{pipeline_id}/shutdown`
 //!   Shutdown a specific pipeline
 //!   - 202 Accepted if the stop request was accepted and is being processed (async operation)
 //!   - 400 Bad Request if the pipeline is already stopped

rust/otap-dataflow/crates/admin/src/pipeline_group.rs

@@ -3,19 +3,19 @@
 
 //! Pipeline group endpoints.
 //!
-//! - GET `/pipeline-groups/:id/pipelines` - list active pipelines and their status (ToDo)
-//! - POST `/pipeline-groups/shutdown` - shutdown all pipelines in all groups
+//! - GET `/api/v1/pipeline-groups/:id/pipelines` - list active pipelines and their status (ToDo)
+//! - POST `/api/v1/pipeline-groups/shutdown` - shutdown all pipelines in all groups
 //!   - Query parameters:
 //!     - `wait` (bool, default: false) - if true, block until all pipelines have stopped
 //!     - `timeout_secs` (u64, default: 60) - maximum seconds to wait when `wait=true`
 //!
 //!   Example (fire-and-forget):
 //!   ```sh
-//!   curl -X POST http://localhost:8080/pipeline-groups/shutdown
+//!   curl -X POST http://localhost:8080/api/v1/pipeline-groups/shutdown
 //!   ```
 //!   Example (wait for graceful shutdown with 30s timeout):
 //!   ```sh
-//!   curl -X POST "http://localhost:8080/pipeline-groups/shutdown?wait=true&timeout_secs=30"
+//!   curl -X POST "http://localhost:8080/api/v1/pipeline-groups/shutdown?wait=true&timeout_secs=30"
 //!   ```
 //!
 //!   - 200 OK if `wait=true` and all pipelines stopped successfully
@@ -113,7 +113,8 @@ async fn shutdown_all_pipelines(
             sender
                 .try_send_shutdown(
                     deadline,
-                    "Shutdown requested via the `/pipeline-groups/shutdown` endpoint.".to_owned(),
+                    "Shutdown requested via the `/api/v1/pipeline-groups/shutdown` endpoint."
+                        .to_owned(),
                 )
                 .err()
         })

rust/otap-dataflow/crates/admin/src/telemetry.rs

@@ -3,10 +3,10 @@
 
 //! Telemetry endpoints.
 //!
-//! - /telemetry/live-schema - current semantic conventions registry
-//! - /telemetry/logs - retained internal logs from the in-memory log tap
-//! - /telemetry/metrics - current aggregated metrics in JSON, line protocol, or Prometheus text format
-//! - /telemetry/metrics/aggregate - aggregated metrics grouped by metric set name and optional attributes
+//! - /api/v1/telemetry/live-schema - current semantic conventions registry
+//! - /api/v1/telemetry/logs - retained internal logs from the in-memory log tap
+//! - /api/v1/telemetry/metrics - current aggregated metrics in JSON, line protocol, or Prometheus text format
+//! - /api/v1/telemetry/metrics/aggregate - aggregated metrics grouped by metric set name and optional attributes
 
 use crate::AppState;
 use axum::extract::{Query, State};
@@ -94,7 +94,7 @@ pub enum OutputFormat {
     Prometheus,
 }
 
-/// Query parameters for /telemetry/metrics
+/// Query parameters for /api/v1/telemetry/metrics
 #[derive(Debug, Default, Deserialize)]
 pub struct MetricsQuery {
     /// When true, reset metrics after reading. Default: false.
@@ -108,7 +108,7 @@ pub struct MetricsQuery {
     keep_all_zeroes: bool,
 }
 
-/// Query parameters for /telemetry/metrics/aggregate
+/// Query parameters for /api/v1/telemetry/metrics/aggregate
 #[derive(Debug, Default, Deserialize)]
 pub struct AggregateQuery {
     /// When true, reset metrics after reading. Default: false.
@@ -122,7 +122,7 @@ pub struct AggregateQuery {
     format: Option<OutputFormat>,
 }
 
-/// Query parameters for /telemetry/logs
+/// Query parameters for /api/v1/telemetry/logs
 #[derive(Debug, Default, Deserialize)]
 pub struct LogsQuery {
     /// Return logs strictly newer than this sequence number.
@@ -271,7 +271,7 @@ pub async fn get_logs(
     Ok(Json(logs_response(&state.metrics_registry, result)))
 }
 
-/// Handler for the `/telemetry/metrics` endpoint.
+/// Handler for the `/api/v1/telemetry/metrics` endpoint.
 /// Supports multiple output formats and optional reset.
 ///
 /// Query parameters:
@@ -346,7 +346,7 @@ pub async fn get_metrics(
     }
 }
 
-/// Handler for the /telemetry/metrics/aggregate endpoint.
+/// Handler for the /api/v1/telemetry/metrics/aggregate endpoint.
 /// Aggregates metrics by metric set name and optionally by a list of attributes.
 ///
 /// Query parameters:

rust/otap-dataflow/crates/admin/ui/js/metrics-api.js

@@ -13,7 +13,7 @@ function dedupeUrls(urls) {
 // Build same-origin metrics endpoint candidates.
 // The embedded UI should read from its own admin origin.
 export function buildMetricsCandidates({ query }) {
-  const localPaths = ["/telemetry/metrics", "/metrics"];
+  const localPaths = ["/api/v1/telemetry/metrics", "/api/v1/metrics"];
   const localUrls = localPaths.map((path) => `${path}?${query}`);
   return dedupeUrls(localUrls);
 }

rust/otap-dataflow/crates/admin/ui/js/polling-controller.js

@@ -236,8 +236,8 @@ export async function runHealthPoll({
   const checkedAt = Date.now();
   try {
     const [livezProbe, readyzProbe] = await Promise.all([
-      probeHealthEndpoint("/livez", healthRequestTimeoutMs),
-      probeHealthEndpoint("/readyz", healthRequestTimeoutMs),
+      probeHealthEndpoint("/api/v1/livez", healthRequestTimeoutMs),
+      probeHealthEndpoint("/api/v1/readyz", healthRequestTimeoutMs),
     ]);
     livezProbe.checkedAt = checkedAt;
     readyzProbe.checkedAt = checkedAt;
@@ -269,7 +269,7 @@ export async function runStatusPoll({
   }, statusRequestTimeoutMs);
 
   try {
-    const response = await fetch("/status", {
+    const response = await fetch("/api/v1/status", {
       method: "GET",
       cache: "no-store",
       signal: controller.signal,

rust/otap-dataflow/crates/validation/src/simulate.rs

@@ -78,7 +78,7 @@ async fn wait_for_ready(
     max_retry: usize,
     retry_cooldown: Duration,
 ) -> Result<(), ValidationError> {
-    let readyz_url = format!("{base}/readyz");
+    let readyz_url = format!("{base}/api/v1/readyz");
     let mut last_error: Option<String> = None;
     for _attempt in 0..max_retry {
         match client.get(&readyz_url).send().await {
@@ -102,15 +102,17 @@ async fn wait_for_ready(
 
 async fn fetch_metrics(client: &Client, base: &str) -> Result<MetricsSnapshot, ValidationError> {
     client
-        .get(format!("{base}/telemetry/metrics"))
+        .get(format!("{base}/api/v1/telemetry/metrics"))
         .query(&[
             ("reset", "false"),
             ("keep_all_zeroes", "true"),
             ("format", "json"),
         ])
         .send()
         .await
-        .map_err(|_| ValidationError::Http(format!("No Response from {base}/telemetry/metrics")))?
+        .map_err(|_| {
+            ValidationError::Http(format!("No Response from {base}/api/v1/telemetry/metrics"))
+        })?
         .error_for_status()
         .map_err(|e| ValidationError::Http(e.to_string()))?
         .json()
@@ -161,7 +163,7 @@ async fn wait_for_validation_finished(
 /// shutdown pipeline after running
 async fn shutdown_pipeline(client: &Client, base: &str) -> Result<(), ValidationError> {
     let _ = client
-        .post(format!("{base}/pipeline-groups/shutdown"))
+        .post(format!("{base}/api/v1/pipeline-groups/shutdown"))
         .send()
         .await
         .map_err(|e| ValidationError::Http(e.to_string()))?

rust/otap-dataflow/docs/admin/architecture.md

@@ -25,7 +25,7 @@ Request flow:
 
 1. `GET /` or `GET /dashboard` serves the embedded UI shell.
 2. Browser loads static assets from `/static/*`.
-3. UI polls `/telemetry/metrics` (or `/metrics` alias) with:
+3. UI polls `/api/v1/telemetry/metrics` (or `/api/v1/metrics` alias) with:
    - `format=json`
    - `reset=false`
    - optional `keep_all_zeroes=true|false`
@@ -34,8 +34,8 @@ Request flow:
 
 When calling endpoints directly outside browser-relative paths, use:
 
-- `http://<admin-host>:<admin-port>/telemetry/metrics`
-- `http://<admin-host>:<admin-port>/metrics`
+- `http://<admin-host>:<admin-port>/api/v1/telemetry/metrics`
+- `http://<admin-host>:<admin-port>/api/v1/metrics`
 
 ## Main design principles
 
@@ -60,8 +60,8 @@ When calling endpoints directly outside browser-relative paths, use:
 
 `metrics-api.js` builds same-origin candidates only:
 
-1. `/telemetry/metrics?...`
-2. `/metrics?...`
+1. `/api/v1/telemetry/metrics?...`
+2. `/api/v1/metrics?...`
 
 `fetchMetricsFromCandidates()` probes candidates in order and caches the first
 successful URL for the next cycle.