Deprecated REST API Migration Guide | UFM Cable Validation Tool

1. Deprecated REST API Migration Guide

1.1. Overview

Several legacy REST API endpoints have been removed from the Cable Validation Tool (CVT) and replaced with dedicated, purpose-built endpoints. This guide helps users migrate from the deprecated APIs to their replacements.

The changes fall into two categories:

CommandProc endpoints (/commands/*) — a generic command-execution router that has been replaced by dedicated REST endpoints for each feature area.
Device exclude/unexclude endpoints (/devices/exclude, /devices/unexclude, /devices/excluded) — replaced by the unified Device Status Management API.

1.2. CommandProc Endpoints

The legacy /commands/* API allowed callers to execute CLI commands over HTTP through a single generic router. This has been retired in favor of dedicated REST endpoints that follow standard HTTP conventions (proper methods, structured request/response bodies, and per-operation status polling).

1.2.1. 1 Generic Routes (Removed)

These meta-endpoints provided command discovery, execution status, and help. They have no direct replacements because each feature area now exposes its own endpoints.

Deprecated Endpoint	Method	Description	Replacement
`/commands`	`GET`	List all supported commands	No replacement. Available actions are expressed by the individual REST endpoints listed below.
`/commands/status`	`GET`	Global command execution status (idle / executing)	No replacement.
`/commands/{command_name}`	`POST`	Execute a command by name	See per-command mapping below.
`/commands/{command_name}/output`	`GET`	Poll the output of a running command	Each feature now has its own result-polling endpoint (e.g. `GET /validation/result`, `GET /agents/manage/result`, `GET /topology/action/result`).
`/commands/{command_name}/help`	`GET`	Get help text for a command	No replacement.

1.2.2. 2 Topology Loading

All topology loading commands now use the POST /topology/load/{type} pattern. These are asynchronous — the server returns 202 Accepted immediately and progress is tracked by polling GET /topology/action/result.

Deprecated Command	Replacement Endpoint	Method	Request Body
`load_topo`	`/topology/load/topo`	`POST`	`{"files": [...], "dns": true}`
`load_ip`	`/topology/load/ip`	`POST`	`{"files": [...]}`
`load_ptp`	`/topology/load/ptp`	`POST`	`{"file": "...", "format": "...", "sheets": [...], "dns": true, "dc_layout": "...", "hca_mapping": "..."}`
`load`	No replacement	—	The `load` command loaded from a saved file prefix. JSON topology can be loaded via `POST /topology/load/json` instead.

Polling: GET /topology/action/result (also GET /topology/load/result for backward compatibility).

1.2.3. 3 Credential Management

Credential commands are replaced by RESTful endpoints under /creds/*. All are synchronous (immediate response).

Deprecated Command	Replacement Endpoint	Method	Request Body
`set_default_creds`	`/creds/defaults/{node_type}`	`POST`	`{"user": "...", "pwd": "...", "save": true}` where `node_type` is `switch` or `host`
`set_node_creds`	`/creds/nodes/{node_id}`	`POST`	`{"user": "...", "pwd": "...", "save": true}`
`set_credential_profile`	`/creds/profiles/{profile_name}`	`POST`	`{"user": "...", "pwd": "...", "save": true}`
`remove_node_creds`	`/creds/nodes/{node_id}`	`DELETE`	—
`remove_credential_profile`	`/creds/profiles/{profile_name}`	`DELETE`	—

Additional credential endpoints:

GET /creds — list all credentials
GET /creds?credential_profile=true — list all credential profiles
POST /creds/upload — upload a credentials file (multipart form)

1.2.4. 4 User Management

Deprecated Command	Replacement Endpoint	Method	Notes
`load_web_users`	`/users/upload`	`POST`	Multipart form with a `file` field (JSON) and an optional `delete_existing_users` field. Synchronous.

1.2.5. 5 Agent Deployment

The three separate deploy commands (deploy_all_agents, deploy_single_agent, deploy_agents) are unified into a single POST /agents/deploy endpoint. Similarly, the three remove commands are unified into POST /agents/remove. Both return 202 Accepted and are polled via GET /agents/manage/result.

Deprecated Command	Replacement Endpoint	Method	Request Body
`deploy_all_agents`	`/agents/deploy`	`POST`	`{"all": true}`
`deploy_single_agent`	`/agents/deploy`	`POST`	`{"switches": ["<switch>"]}`
`deploy_agents`	`/agents/deploy`	`POST`	`{"switches": ["<switch1>", "<switch2>", ...]}`
`remove_all_agents`	`/agents/remove`	`POST`	`{"all": true}`
`remove_single_agent`	`/agents/remove`	`POST`	`{"switches": ["<switch>"]}`
`remove_agents`	`/agents/remove`	`POST`	`{"switches": ["<switch1>", "<switch2>", ...]}`

Polling: GET /agents/manage/result

1.2.6. 6 Validation

Deprecated Command	Replacement Endpoint	Method	Request Body
`start_validation`	`/validation`	`POST`	`{"timeout": "..."}` (optional)
`stop_validation`	`/validation`	`DELETE`	—

Polling: GET /validation/result

1.2.7. 7 Switch Status and Connectivity

Deprecated Command	Replacement Endpoint	Method	Notes
`check_switch_status`	`/agents/connectivity/check`	`POST`	Returns `202 Accepted`. Poll `GET /agents/connectivity/check/result`.
`show_switches`	`/resources/nodes`	`GET`	Synchronous. Returns all nodes with full device information.

1.2.8. 8 Commands Without a Replacement

Deprecated Command	Reason
`load`	Loaded topology from a saved file prefix. Use `POST /topology/load/json` for JSON topologies instead.
`add_certificate`	Certificate management is handled at the Apache/infrastructure layer.
`show_switch_history`	Not currently exposed as a REST endpoint.
`amber_show_latest`	The full amber report is available via `GET /report/amber`, but the filtered "latest" view has no direct equivalent.

1.2.9. 9 Server Shutdown

Deprecated Command	Replacement Endpoint	Method	Notes
`exit`	`/cv_controller/stop`	`POST`	Synchronous. Important: this endpoint is served by the CV Controller service (Apache location `/cv_controller`), not by the main `/cablevalidation` service where `/commands/*` used to live.

1.3. Device Exclude/Unexclude Endpoints

The device exclusion mechanism has been replaced by a unified Device Status Management API. Instead of a simple excluded/not-excluded binary, each device now has a status (e.g. VALIDATION_READY, UNMANAGED, UNSUPPORTED) with controlled transitions and audit history.

1.3.1. 1 Endpoint Migration

Deprecated Endpoint	Method	Replacement Endpoint	Method	Request Body / Notes
`/devices/excluded`	`GET`	`/resources/nodes`	`GET`	Each node object now includes a `status` field. Filter for `UNMANAGED` status to find previously "excluded" devices.
`/devices/exclude`	`POST`	`/devices/status`	`PUT`	`{"devices": [...], "status": "UNMANAGED", "reason": "..."}`
`/devices/unexclude`	`DELETE`	`/devices/status`	`PUT`	`{"devices": [...], "status": "VALIDATION_READY", "reason": "..."}`

1.3.2. 2 New Device Status Endpoints

The following endpoints provide richer device lifecycle management:

Endpoint	Method	Description

Endpoint	Method	Description
`/devices/status/{device_name}`	`PUT`	Set the status of a single device. Body: `{"status": "...", "reason": "..."}`
`/devices/status`	`PUT`	Set the status of multiple devices in bulk. Body: `{"devices": [...], "status": "...", "reason": "..."}`
`/devices/status/{device_name}/transitions`	`GET`	Get allowed status transitions for a device (returns current status and valid next statuses).
`/devices/status/{device_name}/history`	`GET`	Get the status change history for a device. Supports `limit` and `offset` query parameters.

1.4. Summary

Category	Deprecated Endpoints	With Replacement	Without Replacement
CommandProc generic routes	5	2 (execute, output)	3 (list, status, help)
CommandProc commands	24	20	4 (`load`, `add_certificate`, `show_switch_history`, `amber_show_latest`)
Device exclude/unexclude	3	3	0
Total	32	25	7

All replacement endpoints are served under the /cablevalidation Apache location unless otherwise noted (the exit replacement is under /cv_controller).

Last updated: June 03, 2026