Implement Clear Data endpoints

[bburda]

Summary

Clear data endpoints allow clients to request the server to reset certain types of cached or stored data on an entity. This is useful for clearing stale caches, resetting learned parameters, or removing client-created temporary resources (like data lists or subscriptions).

The operation is async - the client triggers a clear, then polls a status endpoint.

---

Proposed solution

1. GET /api/v1/{entity-path}/clear-data

List the supported clear-data types for an entity.

Applies to entity types: Components, Apps

Path parameters:

Parameter	Type	Required	Description
{entity-path}	URL segment	Yes	e.g., components/engine_ecu or apps/temp_sensor

Response 200 OK:

{
  "items": [
    { "id": "cached-data", "name": "Cached Data" },
    { "id": "learned-data", "name": "Learned Data" },
    { "id": "client-defined-resources", "name": "Client-Defined Resources" }
  ]
}

Standard clear types:

Type	Description	ROS 2 Mapping
cached-data	Clear the gateway's internal cache of topic data / last-message cache for this entity	Clear NativeSampler's stored messages for entity topics
learned-data	Reset adaptive or learned parameters on the entity	Reset node parameters to defaults (if supported)
client-defined-resources	Remove all client-created temporary resources (data lists, subscriptions, triggers) scoped to this entity	Delete entity's data lists, subscriptions, triggers

Only return types that the implementation actually supports. If only cached-data is implemented, return only that.

---

2. PUT /api/v1/{entity-path}/clear-data/{clear-type}

Trigger a clear operation for the specified data type. The operation runs asynchronously.

Path parameters:

Parameter	Type	Required	Description
{entity-path}	URL segment	Yes	e.g., apps/temp_sensor
{clear-type}	string	Yes	One of: cached-data, learned-data, client-defined-resources

Request body: None

Response 202 Accepted - operation has been started. Poll /clear-data/status for progress.

Error responses:

Status	Error Code	When
400	invalid-parameter	Unknown clear-type value
404	entity-not-found	Entity doesn't exist
409	invalid-request	A clear operation is already in progress for this entity (only one at a time)

The 409 response body:

{
  "error_code": "invalid-request",
  "message": "A clear operation is already in progress",
  "parameters": {
    "current_type": "cached-data",
    "status": "running"
  }
}

---

3. GET /api/v1/{entity-path}/clear-data/status

Poll the status of the last clear operation.

Path parameters:

Parameter	Type	Required	Description
{entity-path}	URL segment	Yes	e.g., apps/temp_sensor

Response 200 OK:

{
  "status": "completed",
  "type": "cached-data",
  "last_started": "2026-02-14T10:30:00Z",
  "progress": 100
}

Field	Type	Required	Description
status	string	Yes	One of: running, completed, failed, notRequested
type	string	Conditional	Which clear type is/was being executed. Present when status ≠ notRequested
last_started	string (ISO 8601)	Conditional	When the clear operation started. Present when status ≠ notRequested
progress	integer	Optional	Percentage 0–100
error	GenericError	Conditional	Error details when status is failed

Status values:

Status	Description
running	Clear operation is in progress
completed	Successfully finished
failed	An error occurred (see error field)
notRequested	No clear operation has been requested for this entity

---

Additional context

Business rules

• No parallel clearing: Only one clear operation can run per entity at a time. Return 409 if another is in progress.
• Status is tracked per entity - each entity independently tracks its last clear operation.

Architecture

• Create a ClearDataHandler class with three handler methods
• Track clear operation status per entity in a thread-safe map
• For cached-data: interact with the gateway's topic data cache to clear stored messages
• For client-defined-resources: coordinate with DataListManager, SubscriptionManager, TriggerManager (when they exist)

Route registration

srv->Get((api_path("/components") + R"(/([^/]+)/clear-data$)"), handler);
srv->Put((api_path("/components") + R"(/([^/]+)/clear-data/([^/]+)$)"), handler);
srv->Get((api_path("/components") + R"(/([^/]+)/clear-data/status$)"), handler);
// Same for /apps/

Important: Register /clear-data/status route before /clear-data/{clear-type} to prevent status from being captured as a clear-type parameter.

Tests

• Unit test: list supported clear types
• Unit test: trigger cached-data clear → 202
• Unit test: poll status → running → completed
• Unit test: trigger while already running → 409
• Unit test: poll with no prior clear → notRequested
• Unit test: unknown clear type → 400