
IoT Edge Data Stream API v1
Use this tool with IoT Edge Connect to read aggregated messages from topics.
Learn more:
Download this API’s RAML and JSON schema descriptors.
Overview
Edge Data Stream is a durable sliding buffer for messages, created as a supplementary tool for IoT Edge Connect.
Use this API to:
Combine messages sent by multiple publishers into a single stream.
Bulk read large streams of data.
Retain the ordering used by the publishing service.
Get started
Use this API alongside the IoT Edge Connect product.
Use the authentication method you’ve configured in your Edge Connect property.
For JWT, you need to pass the token in your request header. Unless you’ve specified otherwise, the header name is
X-Akamai-DCP-Token
.If you selected Mutual Authentication, your authentication is validated alongside your connection to the service. You don’t need to pass any authentication information alongside your request.
This API does not follow Akamai’s standard system of provisioning API tokens within Akamai Control Panel.
API concepts
These concepts clarify the API’s messaging resources:
Topic. An ordered collection of messages.
Message block. A message or group of messages sent from a single topic.
Message. An individual object stored in a topic.
Consumer group. Multiple subscribers sharing a single subscription. All group members receive alternating messages, with each message sent only to one group member. It’s most commonly used for load balancing.
Retained message. It’s an MQTT message automatically sent to the subscriber at the moment of subscribing. It is most commonly used for configuration or status updates.
Resources
This section provides details on the Edge Data Stream API’s various operations and parameters.
API summary
Download the RAML descriptors for this API.
Operation | Method | Endpoint |
---|---|---|
Get messages | GET | /api/ |
Get messages for groups | GET | /api/ |
Get a retained message | GET | /api/ |
Get messages
Reads a set of messages from a single topic.
GET /api/
Sample: /api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
topic |
String | diagnostics%2Fmake%2Fmodel |
The full, URL-encoded path of the topic to read from. This example reads from diagnostics/make/model . |
Optional query parameters | |||
limit |
Integer | 50 |
The maximum number of messages to read. |
offset |
Integer | 500 |
The sequence number of the first message to retrieve. |
Status 200
application/json
Object type: MessageBlock
Download schema: message-block.json
Response body:
{
"messages": [
{
"clientId": "client1",
"payload": "YWJj",
"topicSequenceNumber": 1
},
{
"clientId": "client3",
"payload": "aDEj",
"topicSequenceNumber": 2
}
]
}
Get messages for groups
Reads a set of messages from a single topic for the provided consumer group.
GET /api/
Sample: /api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
topic |
String | diagnostics%2Fmake%2Fmodel |
The full, URL-encoded path of the topic to read from. This example reads from diagnostics/make/model . |
groupId |
String | group1 |
The name of the consumer group. |
Optional query parameters | |||
ack |
Boolean | true |
The message read acknowledgement. |
limit |
Integer | 50 |
The maximum number of messages to read. |
Status 200
application/json
Object type: MessageBlock
Download schema: message-block.json
Response body:
{
"messages": [
{
"clientId": "client1",
"payload": "YWJj",
"topicSequenceNumber": 1
},
{
"clientId": "client3",
"payload": "aDEj",
"topicSequenceNumber": 2
}
],
"token": 1234
}
Get a retained message
Reads the latest retained message from a single topic.
GET /api/
Sample: /api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
topic |
String | diagnostics%2Fmake%2Fmodel |
The full, URL-encoded path of the topic to read from. This example reads from diagnostics/make/model . |
Status 200
application/octet-stream
Response body:
VderKUx2VMqaASsbloD4AWYnnMz3ASDrQhQ
Data
This section provides details on the API’s JSON objects. The basic response is a MessageBlock.
MessageBlock
A collection of messages and metadata.
Download schema:
message-block.json
Sample GET response:
{
"messages": [
{
"clientId": "client1",
"payload": "YWJj",
"topicSequenceNumber": 1
},
{
"clientId": "client3",
"payload": "aDEj",
"topicSequenceNumber": 2
}
]
}
MessageBlock members
Member | Type | Required | Description |
---|---|---|---|
MessageBlock : A collection of messages and metadata. |
|||
messages |
Message |
○ | Messages read from the topic. |
token |
Integer | ○ | The group token. |
MessageBlock.messages[] : Messages read from the topic. |
|||
clientId |
String | ✓ | Identifies the publisher of the message. |
payload |
String | ✓ | The message in base64 format. |
topic |
Integer | ✓ | The sequence number of a message in a topic. |
Errors
This section provides details on the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.
Error responses
The API reports errors with an HTML message.
<HTML><HEAD>
<TITLE>Access Denied</TITLE>
</HEAD><BODY>
<H1>Access Denied</H1>
You don't have permission to access "http:example.com;" on this server.<P>
Reference�
</BODY>
</HTML>
HTTP status codes
The API responds with the following set of HTTP status codes for both success and failure scenarios.
Code | Description |
---|---|
200 | The operation was successful. |
401 | Authentication failure. |
402 | Database error. |
403 | Access is forbidden. |
404 | Resource not found. |
500 | Internal server error. |