[#19] feat: add GET /components/{component_id}/data/{topic_name} endpoint

Michał Fąferek · Michał Fąferek · commit 9b9cb295e8a0 · 2025-11-29T12:53:53.000+01:00
Add endpoint to read specific topic data from a component.
  Fix topic path construction to use namespace_path instead
  of fqn for correct topic discovery.
diff --git a/postman/collections/ros2-medkit-gateway.postman_collection.json b/postman/collections/ros2-medkit-gateway.postman_collection.json
@@ -88,7 +88,7 @@
       "name": "Component Data",
       "item": [
         {
-          "name": "GET Component Data",
+          "name": "GET Component Data (All Topics)",
           "request": {
             "method": "GET",
             "header": [],
@@ -106,6 +106,69 @@
             "description": "Read all topic data from a specific component. Returns array of topic samples with metadata (topic, timestamp, data). Change 'temp_sensor' to other component IDs like 'rpm_sensor', 'pressure_sensor', etc."
           },
           "response": []
+        },
+        {
+          "name": "GET Component Topic Data (Temperature)",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "url": {
+              "raw": "{{base_url}}/components/temp_sensor/data/temperature",
+              "host": [
+                "{{base_url}}"
+              ],
+              "path": [
+                "components",
+                "temp_sensor",
+                "data",
+                "temperature"
+              ]
+            },
+            "description": "Read specific topic data from a component. Returns single topic sample with topic path, timestamp, and data. The topic_name is relative to the component's namespace."
+          },
+          "response": []
+        },
+        {
+          "name": "GET Component Topic Data (RPM)",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "url": {
+              "raw": "{{base_url}}/components/rpm_sensor/data/rpm",
+              "host": [
+                "{{base_url}}"
+              ],
+              "path": [
+                "components",
+                "rpm_sensor",
+                "data",
+                "rpm"
+              ]
+            },
+            "description": "Read RPM topic data from the rpm_sensor component."
+          },
+          "response": []
+        },
+        {
+          "name": "GET Component Topic Data (Pressure)",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "url": {
+              "raw": "{{base_url}}/components/pressure_sensor/data/pressure",
+              "host": [
+                "{{base_url}}"
+              ],
+              "path": [
+                "components",
+                "pressure_sensor",
+                "data",
+                "pressure"
+              ]
+            },
+            "description": "Read brake pressure topic data from the pressure_sensor component."
+          },
+          "response": []
         }
       ]
     }
diff --git a/src/ros2_medkit_gateway/README.md b/src/ros2_medkit_gateway/README.md
@@ -25,6 +25,7 @@ The ROS 2 Medkit Gateway exposes ROS 2 system information and data through a RES
 ### Component Data Endpoints
 
 - `GET /components/{component_id}/data` - Read all topic data from a component
+- `GET /components/{component_id}/data/{topic_name}` - Read specific topic data from a component
 
 ### API Reference
 
@@ -197,11 +198,91 @@ curl http://localhost:8080/components/nonexistent/data
 - Data logging - Periodic sampling of component data
 
 **Performance Considerations:**
-- Topic sampling is currently **sequential** (one topic at a time)
-- Response time scales linearly: `(number of topics) × (timeout per topic)`
-- Example: A component with 10 topics could take up to 30 seconds (10 × 3s)
-- For components with many topics, consider querying specific topics individually
-- **Future improvement**: Parallel topic sampling will be implemented to reduce latency
+- Topic sampling uses **parallel execution** with configurable concurrency
+- Default: up to 10 topics sampled in parallel (configurable via `max_parallel_topic_samples`)
+- Response time scales with batch count: `ceil(topics / batch_size) × timeout`
+- 3-second timeout per topic to accommodate slow-publishing topics
+
+#### GET /components/{component_id}/data/{topic_name}
+
+Read data from a specific topic within a component.
+
+**Example:**
+```bash
+curl http://localhost:8080/components/temp_sensor/data/temperature
+```
+
+**Response (200 OK):**
+```json
+{
+  "topic": "/powertrain/engine/temperature",
+  "timestamp": 1732377600000000000,
+  "data": {
+    "temperature": 85.5,
+    "variance": 0.0
+  }
+}
+```
+
+**Example (Error - Topic Not Found):**
+```bash
+curl http://localhost:8080/components/temp_sensor/data/nonexistent
+```
+
+**Response (404 Not Found):**
+```json
+{
+  "error": "Topic not found or not publishing",
+  "component_id": "temp_sensor",
+  "topic_name": "nonexistent"
+}
+```
+
+**Example (Error - Component Not Found):**
+```bash
+curl http://localhost:8080/components/nonexistent/data/temperature
+```
+
+**Response (404 Not Found):**
+```json
+{
+  "error": "Component not found",
+  "component_id": "nonexistent"
+}
+```
+
+**Example (Error - Invalid Topic Name):**
+```bash
+curl http://localhost:8080/components/temp_sensor/data/invalid-name
+```
+
+**Response (400 Bad Request):**
+```json
+{
+  "error": "Invalid topic name",
+  "details": "Entity ID contains invalid character: '-'. Only alphanumeric and underscore are allowed",
+  "topic_name": "invalid-name"
+}
+```
+
+**URL Parameters:**
+- `component_id` - Component identifier (e.g., `temp_sensor`, `rpm_sensor`)
+- `topic_name` - Topic name within the component (e.g., `temperature`, `rpm`)
+
+**Response Fields:**
+- `topic` - Full topic path (e.g., `/powertrain/engine/temperature`)
+- `timestamp` - Unix timestamp (nanoseconds since epoch) when data was sampled
+- `data` - Topic message data as JSON object
+
+**Validation:**
+- Both `component_id` and `topic_name` follow ROS 2 naming conventions
+- Allowed characters: alphanumeric (a-z, A-Z, 0-9), underscore (_)
+- Hyphens, special characters, and escape sequences are rejected
+
+**Use Cases:**
+- Read specific sensor value (e.g., just temperature, not all engine data)
+- Lower latency than reading all component data
+- Targeted monitoring of specific metrics
 
 ## Quick Start
 
diff --git a/src/ros2_medkit_gateway/include/ros2_medkit_gateway/rest_server.hpp b/src/ros2_medkit_gateway/include/ros2_medkit_gateway/rest_server.hpp
@@ -44,6 +44,7 @@ class RESTServer {
     void handle_list_components(const httplib::Request& req, httplib::Response& res);
     void handle_area_components(const httplib::Request& req, httplib::Response& res);
     void handle_component_data(const httplib::Request& req, httplib::Response& res);
+    void handle_component_topic_data(const httplib::Request& req, httplib::Response& res);
 
     // Helper methods
     std::expected<void, std::string> validate_entity_id(const std::string& entity_id) const;
diff --git a/src/ros2_medkit_gateway/src/rest_server.cpp b/src/ros2_medkit_gateway/src/rest_server.cpp
@@ -60,8 +60,13 @@ void RESTServer::setup_routes() {
         handle_area_components(req, res);
     });
 
-    // Component data
-    server_->Get(R"(/components/([^/]+)/data)", [this](const httplib::Request& req, httplib::Response& res) {
+    // Component topic data (specific topic) - register before general route
+    server_->Get(R"(/components/([^/]+)/data/([^/]+)$)", [this](const httplib::Request& req, httplib::Response& res) {
+        handle_component_topic_data(req, res);
+    });
+
+    // Component data (all topics)
+    server_->Get(R"(/components/([^/]+)/data$)", [this](const httplib::Request& req, httplib::Response& res) {
         handle_component_data(req, res);
     });
 }
@@ -330,7 +335,7 @@ void RESTServer::handle_component_data(const httplib::Request& req, httplib::Res
 
         for (const auto& component : cache.components) {
             if (component.id == component_id) {
-                component_namespace = component.fqn;
+                component_namespace = component.namespace_path;
                 component_found = true;
                 break;
             }
@@ -349,6 +354,7 @@ void RESTServer::handle_component_data(const httplib::Request& req, httplib::Res
         }
 
         // Get component data from DataAccessManager
+        // Use namespace_path to find topics (topics are relative to namespace, not FQN)
         auto data_access_mgr = node_->get_data_access_manager();
         json component_data = data_access_mgr->get_component_data(component_namespace);
 
@@ -372,4 +378,124 @@ void RESTServer::handle_component_data(const httplib::Request& req, httplib::Res
     }
 }
 
+void RESTServer::handle_component_topic_data(const httplib::Request& req, httplib::Response& res) {
+    std::string component_id;
+    std::string topic_name;
+    try {
+        // Extract component_id and topic_name from URL path
+        if (req.matches.size() < 3) {
+            res.status = StatusCode::BadRequest_400;
+            res.set_content(
+                json{{"error", "Invalid request"}}.dump(2),
+                "application/json"
+            );
+            return;
+        }
+
+        component_id = req.matches[1];
+        topic_name = req.matches[2];
+
+        // Validate component_id
+        auto component_validation = validate_entity_id(component_id);
+        if (!component_validation) {
+            res.status = StatusCode::BadRequest_400;
+            res.set_content(
+                json{
+                    {"error", "Invalid component ID"},
+                    {"details", component_validation.error()},
+                    {"component_id", component_id}
+                }.dump(2),
+                "application/json"
+            );
+            return;
+        }
+
+        // Validate topic_name
+        auto topic_validation = validate_entity_id(topic_name);
+        if (!topic_validation) {
+            res.status = StatusCode::BadRequest_400;
+            res.set_content(
+                json{
+                    {"error", "Invalid topic name"},
+                    {"details", topic_validation.error()},
+                    {"topic_name", topic_name}
+                }.dump(2),
+                "application/json"
+            );
+            return;
+        }
+
+        const auto cache = node_->get_entity_cache();
+
+        // Find component in cache
+        std::string component_namespace;
+        bool component_found = false;
+
+        for (const auto& component : cache.components) {
+            if (component.id == component_id) {
+                component_namespace = component.namespace_path;
+                component_found = true;
+                break;
+            }
+        }
+
+        if (!component_found) {
+            res.status = StatusCode::NotFound_404;
+            res.set_content(
+                json{
+                    {"error", "Component not found"},
+                    {"component_id", component_id}
+                }.dump(2),
+                "application/json"
+            );
+            return;
+        }
+
+        // Construct full topic path: {namespace_path}/{topic_name}
+        // Handle root namespace case to avoid double slash (//topic_name)
+        std::string full_topic_path = (component_namespace == "/")
+            ? "/" + topic_name
+            : component_namespace + "/" + topic_name;
+
+        // Get topic data from DataAccessManager
+        auto data_access_mgr = node_->get_data_access_manager();
+        json topic_data = data_access_mgr->get_topic_sample(full_topic_path);
+
+        res.set_content(topic_data.dump(2), "application/json");
+    } catch (const std::exception& e) {
+        // Check if it's a "topic not found" type error
+        std::string error_msg = e.what();
+        if (error_msg.find("not available") != std::string::npos ||
+            error_msg.find("timeout") != std::string::npos) {
+            res.status = StatusCode::NotFound_404;
+            res.set_content(
+                json{
+                    {"error", "Topic not found or not publishing"},
+                    {"component_id", component_id},
+                    {"topic_name", topic_name}
+                }.dump(2),
+                "application/json"
+            );
+        } else {
+            res.status = StatusCode::InternalServerError_500;
+            res.set_content(
+                json{
+                    {"error", "Failed to retrieve topic data"},
+                    {"details", e.what()},
+                    {"component_id", component_id},
+                    {"topic_name", topic_name}
+                }.dump(2),
+                "application/json"
+            );
+        }
+        RCLCPP_ERROR(
+            rclcpp::get_logger("rest_server"),
+            "Error in handle_component_topic_data for component '%s', topic '%s': %s",
+            component_id.c_str(),
+            topic_name.c_str(),
+            e.what()
+        );
+    }
+}
+
 }  // namespace ros2_medkit_gateway
diff --git a/src/ros2_medkit_gateway/test/test_integration.test.py b/src/ros2_medkit_gateway/test/test_integration.test.py
