Edge Data Stream API v1

Use this tool with IoT Edge Connect to read aggregated messages from topics.

Learn more:

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.

API concepts

There are few basic concepts that are important for this API.

  • 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/v1/buffer/topics/{topic}{?offset,limit}
Get Messages for Groups GET /api/v1/buffer/topics/{topic}/groups/{groupId}{?limit,ack}
Get a Retained Message GET /api/v1/buffer/retained/{topic}

Get Messages

This operation reads a set of messages from a single topic.

GET /api/v1/buffer/topics/{topic}{?offset,limit}

Sample: /api/v1/buffer/topics/topic1?offset=500&limit=50

Parameter Type Sample Description
URL parameters
topic String topic1 The name of the topic to read from.
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

Response Body:

{
    "messages": [
        {
            "clientId": "client1",
            "payload": "YWJj",
            "topicSequenceNumber": 1
        },
        {
            "clientId": "client3",
            "payload": "aDEj",
            "topicSequenceNumber": 2
        }
    ]
}

Get Messages for Groups

This operation reads a set of messages from a single topic for the provided consumer group.

GET /api/v1/buffer/topics/{topic}/groups/{groupId}{?limit,ack}

Sample: /api/v1/buffer/topics/topic1/groups/group1?limit=50&ack=true

Parameter Type Sample Description
URL parameters
topic String topic1 The name of the topic to read from.
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

Response Body:

{
    "messages": [
        {
            "clientId": "client1",
            "payload": "YWJj",
            "topicSequenceNumber": 1
        },
        {
            "clientId": "client3",
            "payload": "aDEj",
            "topicSequenceNumber": 2
        }
    ],
    "token": 1234
}

Get a Retained Message

This operation reads the latest retained message from a single topic.

GET /api/v1/buffer/retained/{topic}

Sample: /api/v1/buffer/retained/topic1

Parameter Type Sample Description
URL parameters
topic String topic1 The name of the topic to read from.

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.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

✓ Member is required in requests, or always present in responses, even if its value is empty or null.
○ Member is optional, and may be omitted in some cases.

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
messages MessageBlock.messages[] ○ Messages read from the topic.
token Integer ○ The group token.
MessageBlock.messages[]: Messages read from the topic.
clientId String ✓ Identifies each message’s publisher.
payload String ✓ The message in a base64 format.
topicSequenceNumber Integer ✓ The sequence number of a message in a topic.

Errors

This section provides details on the data object that reflects 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&#12341234
</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.