Description
Spec 1:
Description:
The Reader service currently returns message data in a flat list format. We want to enhance its capabilities to allow flexible grouping of messages in the response based on specified fields. This will support better client-side aggregation and filtering.
Current Format (Flat List Example)
{
"offset": 0,
"limit": 10,
"format": "messages",
"total": 30,
"messages": [
{
"channel": "1674c867-4130-428c-ae6a-896f20656485",
"subtopic": "messages",
"publisher": "c45c08fd-0406-486a-9911-4887fd42b779",
"protocol": "http",
"name": "urn:dev:demo:10001BCD:voltage",
"unit": "V",
"time": 1749633217310000000,
"value": 3.6
},
...
]
}Proposed Enhancements
1. Add Grouping Support via group_by
Introduce a request parameter called group_by, which is an array of field names to group by.
Allowed values:
"timestamp"(required)"channel"(required / optional)"publisher"(required / optional)"protocol"(optional), We can omit this field in result if not given in group"name"(optional) this requires additional parameter"name_prefix"(optional – acts as a filter and partial key)
If
group_byis omitted, the default grouping is:
["timestamp", "channel", "publisher"].
2. Support for Optional Filtering by name_prefix
-
The
name_prefix(e.g.,"urn:dev:demo:10001BCD") can be provided separately or as part ofgroup_by. -
It will act both as:
- a filter to return only messages where
namestarts with this prefix, and - an optional group key, if included in
group_by.
- a filter to return only messages where
3. Grouped Response Format
If format=grouped is specified, the API should return the following structure options:
3.1 Option 1
{
"offset": 0,
"limit": 10,
"format": "grouped",
"total": 30,
"messages": [
{
"timestamp": 1749633217310000000,
"channel": "1674c867-4130-428c-ae6a-896f20656485",
"publisher": "c45c08fd-0406-486a-9911-4887fd42b779",
"protocol": "http",
"messages": [
{
"name": "urn:dev:demo:10001BCD:voltage",
"value": 3.6
},
{
"name": "urn:dev:demo:10001BCD:current",
"value": 3.6
},
...
]
}
]
}🔸
unitcan be omitted in grouped responses, since it's considered constant pername.
3.2 Option 2
{
"offset": 0,
"limit": 10,
"format": "grouped",
"total": 30,
"messages": [
{
"timestamp": 1749633217310000000,
"channel": "1674c867-4130-428c-ae6a-896f20656485",
"publisher": "c45c08fd-0406-486a-9911-4887fd42b779",
"protocol": "http",
"metrics": [
{
"voltage": 110.12,
"current" : 1.2,
},
...
]
}
]
}4. Backward Compatibility
- The current flat list format should remain available via
format=messages(default). - Grouped format is opt-in via
format=grouped.
Example Request with Grouping
curl http://localhost/readers/m/<domain_id>/c/<channed_id/?format=grouped&group_by=["timestamp", "channel", "publisher", "protocol", "name"]&name_prefix=urn:dev:demo:10001BCD&limit=10&offset=0Summary
This spec introduces:
- Flexible grouping via
group_by - Optional filtering and grouping by
name_prefix - Grouped response structure
- Omission of constant fields like
unit - Backward-compatible design
This will enable more efficient and structured access to historical data for visualization, analytics, and reporting use cases.
Spec 2:
ToDo